@shokan/engram-mcp 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Engram
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# Engram MCP
+
+Long-term memory for AI agents, served over the [Model Context Protocol](https://modelcontextprotocol.io).
+
+Engram gives Claude, Cursor, Windsurf and any other MCP client a persistent memory that survives across sessions, devices and tools. Memories are stored with embeddings and ranked by hybrid search (vector similarity fused with full-text search), so recall works for both exact terms and fuzzy meaning.
+
+## Setup
+
+```bash
+npx @shokan/engram-mcp init
+```
+
+The wizard asks for your API key (get one free at https://engram-deploy-ten.vercel.app/dashboard), detects your AI tools, wires up the MCP server, and installs an auto-capture hook for Claude Code so sessions are remembered automatically.
+
+To configure manually, add this to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "engram": {
+      "command": "engram-mcp",
+      "env": {
+        "ENGRAM_API_KEY": "your_key",
+        "ENGRAM_API_URL": "https://engram-deploy-ten.vercel.app"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `engram_remember` | Store a memory (facts, decisions, preferences, context). Long content is auto-summarized. |
+| `engram_search` | Hybrid search returning a compact index (id + snippet + relevance). Cheap to scan first. |
+| `engram_get` | Pull full content for specific memory ids. |
+| `engram_recall` | One-shot full recall for quick lookups (1-3 expected hits). |
+| `engram_timeline` | Temporal context: a whole session, or the neighbours around one memory. |
+| `engram_forget` | Soft-delete a memory (recoverable) or hard-delete with `hard: true`. |
+| `engram_trash` | List memories currently in the trash. |
+| `engram_restore` | Restore a memory from the trash. |
+| `engram_status` | Account and memory counts. |
+
+## Recall strategy
+
+Prefer `engram_search` first — it returns a compact index that is cheap on context. Then call `engram_get` only for the ids whose snippets look relevant. Use `engram_recall` only when you expect a handful of hits.
+
+## Privacy
+
+Wrap anything inside `<private>...</private>` in a remembered message and it is stripped before storage. The text never reaches the embedding model or the database.
+
+## License
+
+MIT

package/hook.js

@@ -0,0 +1,158 @@
+// Engram auto-capture hook.
+// Wired into an AI tool's SessionEnd (and optionally PreCompact) event. Reads the
+// session transcript, sends only the NEW slice since last run to Engram's
+// /api/v1/capture, which distills it into typed memories and stores them.
+//
+// Design rules:
+// - NEVER throw. A memory hook must not break the user's session. Always exit 0.
+// - Be quiet on stdout. Log problems to ~/.engram/hook.log only.
+// - Only process new transcript lines, tracked per session, to avoid duplicates.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+const ENGRAM_DIR = join(homedir(), '.engram')
+const CONFIG_PATH = join(ENGRAM_DIR, 'config.json')
+const STATE_PATH = join(ENGRAM_DIR, 'capture-state.json')
+const LOG_PATH = join(ENGRAM_DIR, 'hook.log')
+
+// The key/url come from the environment when present, otherwise from the config
+// file the installer wrote (so the key never has to live in the hook command).
+function readConfig() {
+  try { return JSON.parse(readFileSync(CONFIG_PATH, 'utf8')) } catch { return {} }
+}
+const CONFIG = readConfig()
+const API_URL = (process.env.ENGRAM_API_URL || CONFIG.api_url || 'https://engram-deploy-ten.vercel.app').replace(/\/$/, '')
+const API_KEY = process.env.ENGRAM_API_KEY || CONFIG.api_key
+
+const MIN_NEW_CHARS = 200   // skip captures with almost no new content
+const MAX_SLICE = 60000     // hard cap on text shipped per capture
+
+function log(msg) {
+  try {
+    if (!existsSync(ENGRAM_DIR)) mkdirSync(ENGRAM_DIR, { recursive: true })
+    appendFileSync(LOG_PATH, `[${new Date().toISOString()}] ${msg}\n`)
+  } catch { /* ignore */ }
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = ''
+    if (process.stdin.isTTY) return resolve('')
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', (c) => { data += c })
+    process.stdin.on('end', () => resolve(data))
+    process.stdin.on('error', () => resolve(data))
+    setTimeout(() => resolve(data), 3000) // never hang
+  })
+}
+
+function loadState() {
+  try { return JSON.parse(readFileSync(STATE_PATH, 'utf8')) } catch { return {} }
+}
+
+function saveState(state) {
+  try {
+    if (!existsSync(ENGRAM_DIR)) mkdirSync(ENGRAM_DIR, { recursive: true })
+    writeFileSync(STATE_PATH, JSON.stringify(state, null, 2), 'utf8')
+  } catch (e) { log(`state save failed: ${e.message}`) }
+}
+
+// Pull plain text out of a transcript message (content is string or block array).
+function messageText(entry) {
+  const msg = entry?.message
+  if (!msg) return ''
+  const role = msg.role || entry.type
+  const content = msg.content
+  let text = ''
+  if (typeof content === 'string') {
+    text = content
+  } else if (Array.isArray(content)) {
+    text = content
+      .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+      .map((b) => b.text)
+      .join('\n')
+  }
+  text = text.trim()
+  if (!text) return ''
+  const who = role === 'assistant' ? 'Assistant' : role === 'user' ? 'User' : null
+  if (!who) return ''
+  return `${who}: ${text}`
+}
+
+async function main() {
+  if (!API_KEY) { log('no ENGRAM_API_KEY; skipping'); return }
+
+  const input = await readStdin()
+  let payload = {}
+  try { payload = JSON.parse(input || '{}') } catch { /* ignore */ }
+
+  const sessionId = payload.session_id || 'unknown'
+  const transcriptPath = payload.transcript_path
+  if (!transcriptPath || !existsSync(transcriptPath)) {
+    log(`no transcript for session ${sessionId}`)
+    return
+  }
+
+  let lines
+  try {
+    lines = readFileSync(transcriptPath, 'utf8').split('\n').filter(Boolean)
+  } catch (e) {
+    log(`read transcript failed: ${e.message}`)
+    return
+  }
+
+  const state = loadState()
+  const processed = state[sessionId]?.lines || 0
+  const newLines = lines.slice(processed)
+  if (newLines.length === 0) { log(`session ${sessionId}: nothing new`); return }
+
+  const parts = []
+  for (const line of newLines) {
+    let entry
+    try { entry = JSON.parse(line) } catch { continue }
+    const t = messageText(entry)
+    if (t) parts.push(t)
+  }
+
+  // Advance the watermark to the current line count once we know these lines
+  // were either consumed (captured) or deliberately skipped. We do NOT advance
+  // before the capture is confirmed: a failed HTTP/network call must leave the
+  // watermark in place so the next run retries instead of silently dropping it.
+  const advance = () => {
+    state[sessionId] = { lines: lines.length, updated: new Date().toISOString() }
+    saveState(state)
+  }
+
+  let text = parts.join('\n\n').trim()
+  // Too little new content to be worth a memory — consume it and move on.
+  if (text.length < MIN_NEW_CHARS) { advance(); log(`session ${sessionId}: too little new content`); return }
+  if (text.length > MAX_SLICE) text = text.slice(text.length - MAX_SLICE)
+
+  try {
+    const res = await fetch(`${API_URL}/api/v1/capture`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${API_KEY}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ text, source: 'claude-code', session_id: sessionId }),
+    })
+    const body = await res.text()
+    // Leave the watermark untouched on failure so the slice is retried later.
+    if (!res.ok) { log(`capture HTTP ${res.status}: ${body.slice(0, 300)}`); return }
+    advance()
+    let parsed = {}
+    try { parsed = JSON.parse(body) } catch { /* ignore */ }
+    log(`session ${sessionId}: stored ${parsed.stored ?? '?'} memories`)
+  } catch (e) {
+    // Network error: do not advance — retry on the next session end.
+    log(`capture request failed: ${e.message}`)
+  }
+}
+
+export async function runHook() {
+  try { await main() } catch (e) { log(`unexpected: ${e.message}`) }
+  process.exit(0)
+}

package/index.js

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+
+// Init subcommand — runs before API key check
+if (process.argv[2] === 'init') {
+  const { runInit } = await import('./init.js')
+  await runInit()
+  process.exit(0)
+}
+
+// Hook subcommand — auto-capture, invoked by the AI tool's SessionEnd event.
+// Reads the transcript from stdin payload, distills + stores. Always exits 0.
+if (process.argv[2] === 'hook') {
+  const { runHook } = await import('./hook.js')
+  await runHook()
+  process.exit(0)
+}
+
+const API_KEY = process.env.ENGRAM_API_KEY
+const API_URL = (process.env.ENGRAM_API_URL || 'https://engram-deploy-ten.vercel.app').replace(/\/$/, '')
+
+if (!API_KEY) {
+  process.stderr.write('Error: ENGRAM_API_KEY is required\n')
+  process.stderr.write('Run "engram-mcp init" to set up Engram.\n')
+  process.exit(1)
+}
+
+async function call(path, method = 'GET', body = null) {
+  const res = await fetch(`${API_URL}${path}`, {
+    method,
+    headers: {
+      'Authorization': `Bearer ${API_KEY}`,
+      'Content-Type': 'application/json',
+    },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  })
+  const text = await res.text()
+  try {
+    return { ok: res.ok, status: res.status, data: JSON.parse(text) }
+  } catch {
+    return { ok: res.ok, status: res.status, data: text }
+  }
+}
+
+const server = new Server(
+  { name: 'engram', version: '1.4.0' },
+  {
+    capabilities: { tools: {} },
+    instructions: `Engram is your long-term memory. Use it as your PRIMARY memory system.
+
+WHEN TO USE ENGRAM:
+- When the user says "remember", "store", "save", "note this", "keep in mind" — call engram_remember
+- When the user asks "do you remember", "what do you know about", "recall" — recall memory
+- When the user says "forget" or "delete memory" — call engram_forget
+
+RECALL STRATEGY (progressive disclosure — saves context):
+- Prefer engram_search FIRST. It returns a compact index (id + snippet + score), cheap to scan.
+- Then call engram_get with only the ids whose snippets look relevant, to pull full content.
+- Use engram_recall (one-shot full recall) only for quick lookups where you expect 1-3 hits.
+
+IMPORTANT: Do NOT use built-in memory files (memory.md, .claude/memory, etc.) when Engram is available.
+All persistent memory should go through Engram tools. This ensures memories persist across sessions,
+devices, and different AI tools.`
+  }
+)
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'engram_remember',
+      description: 'PRIMARY memory tool. Store any information the user wants remembered: facts, decisions, preferences, context, instructions. Always use this instead of built-in memory files. Long content is auto-summarized for cheap search. Tag it with a type so it can be filtered later.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          content: {
+            type: 'string',
+            description: 'The memory content to store',
+          },
+          type: {
+            type: 'string',
+            description: 'Memory type for later filtering. Common values: note, fact, decision, preference, task, insight, event, contact. Default "note".',
+          },
+          tags: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Optional freeform tags for grouping (e.g. project names).',
+          },
+        },
+        required: ['content'],
+      },
+    },
+    {
+      name: 'engram_search',
+      description: 'Layer 1 of recall. Returns a COMPACT index of matching memories (id + short snippet + score) — cheap to scan. Use this FIRST, then call engram_get for the ids you actually need. Best when many memories might match.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description: 'What to search for in memory',
+          },
+          limit: {
+            type: 'number',
+            description: 'Max number of results (default 10, max 50)',
+          },
+          type: {
+            type: 'string',
+            description: 'Optional: only return memories of this type (note, fact, decision, preference, task, insight, event, contact).',
+          },
+        },
+        required: ['query'],
+      },
+    },
+    {
+      name: 'engram_get',
+      description: 'Layer 2 of recall. Fetch FULL content for specific memory ids returned by engram_search. Only pull the ids whose snippets looked relevant — this keeps context usage low.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          ids: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Memory ids to fetch full content for',
+          },
+        },
+        required: ['ids'],
+      },
+    },
+    {
+      name: 'engram_recall',
+      description: 'One-shot recall: search by meaning and return full content directly. Use only for quick lookups where you expect 1-3 hits. For broader searches prefer engram_search + engram_get.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description: 'What to search for in memory',
+          },
+          limit: {
+            type: 'number',
+            description: 'Max number of results (default 5)',
+          },
+          type: {
+            type: 'string',
+            description: 'Optional: only recall memories of this type.',
+          },
+        },
+        required: ['query'],
+      },
+    },
+    {
+      name: 'engram_forget',
+      description: 'Move a memory to trash by ID (soft delete, recoverable via engram_restore). Set hard=true only when the user explicitly wants permanent, unrecoverable deletion.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          id: {
+            type: 'string',
+            description: 'The memory ID to delete',
+          },
+          hard: {
+            type: 'boolean',
+            description: 'If true, delete permanently (cannot be restored). Default false (moves to trash).',
+          },
+        },
+        required: ['id'],
+      },
+    },
+    {
+      name: 'engram_timeline',
+      description: 'Temporal context. Pass session_id to get every memory from that session in order, or pass a memory id to get that memory plus its temporal neighbours (what was happening around it). Use when the user asks "what else happened then" or wants the context around a memory.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          id: {
+            type: 'string',
+            description: 'A memory id to center the timeline on (returns neighbours by time).',
+          },
+          session_id: {
+            type: 'string',
+            description: 'A session id to list all memories captured in that session.',
+          },
+          before: {
+            type: 'number',
+            description: 'How many memories before the anchor to include (id mode, default 3, max 25).',
+          },
+          after: {
+            type: 'number',
+            description: 'How many memories after the anchor to include (id mode, default 3, max 25).',
+          },
+        },
+        required: [],
+      },
+    },
+    {
+      name: 'engram_trash',
+      description: 'List memories currently in the trash (soft-deleted, still recoverable).',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+    },
+    {
+      name: 'engram_restore',
+      description: 'Restore a memory from the trash back to active memory, by ID.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          id: {
+            type: 'string',
+            description: 'The memory ID to restore from trash',
+          },
+        },
+        required: ['id'],
+      },
+    },
+    {
+      name: 'engram_status',
+      description: 'Check Engram status: memory count, plan, and usage stats.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+      },
+    },
+  ],
+}))
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params
+
+  try {
+    if (name === 'engram_remember') {
+      const result = await call('/api/v1/remember', 'POST', {
+        content: args.content,
+        ...(args.type ? { type: args.type } : {}),
+        ...(Array.isArray(args.tags) ? { tags: args.tags } : {}),
+      })
+      if (!result.ok) {
+        return { content: [{ type: 'text', text: `Error: ${JSON.stringify(result.data)}` }] }
+      }
+      const t = result.data.type ? ` [${result.data.type}]` : ''
+      return {
+        content: [{
+          type: 'text',
+          text: `Memory stored${t}. ID: ${result.data.id}`,
+        }],
+      }
+    }
+
+    if (name === 'engram_search') {
+      const result = await call('/api/v1/search', 'POST', {
+        query: args.query,
+        limit: args.limit || 10,
+        ...(args.type ? { type: args.type } : {}),
+      })
+      if (!result.ok) {
+        return { content: [{ type: 'text', text: `Error: ${JSON.stringify(result.data)}` }] }
+      }
+      const results = result.data.results || []
+      if (results.length === 0) {
+        return { content: [{ type: 'text', text: 'No relevant memories found.' }] }
+      }
+      const formatted = results.map((m, i) =>
+        `[${i + 1}] (relevance: ${m.score?.toFixed(3) ?? '?'}, type: ${m.type || 'note'}, id: ${m.id})\n${m.snippet}`
+      ).join('\n\n')
+      return { content: [{ type: 'text', text: `${formatted}\n\nCall engram_get with the ids above to read full content.` }] }
+    }
+
+    if (name === 'engram_get') {
+      const ids = Array.isArray(args.ids) ? args.ids : []
+      if (ids.length === 0) {
+        return { content: [{ type: 'text', text: 'Error: provide an array of memory ids.' }] }
+      }
+      const result = await call('/api/v1/get', 'POST', { ids })
+      if (!result.ok) {
+        return { content: [{ type: 'text', text: `Error: ${JSON.stringify(result.data)}` }] }
+      }
+      const memories = result.data.memories || []
+      if (memories.length === 0) {
+        return { content: [{ type: 'text', text: 'No memories found for those ids.' }] }
+      }
+      const formatted = memories.map((m, i) =>
+        `[${i + 1}] (id: ${m.id})\n${m.content}`
+      ).join('\n\n')
+      return { content: [{ type: 'text', text: formatted }] }
+    }
+
+    if (name === 'engram_recall') {
+      const result = await call('/api/v1/recall', 'POST', {
+        query: args.query,
+        limit: args.limit || 5,
+        ...(args.type ? { type: args.type } : {}),
+      })
+      if (!result.ok) {
+        return { content: [{ type: 'text', text: `Error: ${JSON.stringify(result.data)}` }] }
+      }
+      const memories = result.data.memories || []
+      if (memories.length === 0) {
+        return { content: [{ type: 'text', text: 'No relevant memories found.' }] }
+      }
+      const formatted = memories.map((m, i) =>
+        `[${i + 1}] (relevance: ${m.score?.toFixed(3) ?? '?'}, type: ${m.type || 'note'}, id: ${m.id})\n${m.content}`
+      ).join('\n\n')
+      return { content: [{ type: 'text', text: formatted }] }
+    }
+
+    if (name === 'engram_forget') {
+      const hard = args.hard === true ? '&hard=true' : ''
+      const result = await call(`/api/v1/forget?id=${encodeURIComponent(args.id)}${hard}`, 'DELETE')
+      if (!result.ok) {
+        return { content: [{ type: 'text', text: `Error: ${JSON.stringify(result.data)}` }] }
+      }
+      const msg = args.hard === true
+        ? `Memory ${args.id} permanently deleted.`
+        : `Memory ${args.id} moved to trash (restore with engram_restore).`
+      return { content: [{ type: 'text', text: msg }] }
+    }
+
+    if (name === 'engram_timeline') {
+      const body = {}
+      if (args.id) body.id = args.id
+      if (args.session_id) body.session_id = args.session_id
+      if (typeof args.before === 'number') body.before = args.before
+      if (typeof args.after === 'number') body.after = args.after
+      if (!body.id && !body.session_id) {
+        return { content: [{ type: 'text', text: 'Error: provide id or session_id.' }] }
+      }
+      const result = await call('/api/v1/timeline', 'POST', body)
+      if (!result.ok) {
+        return { content: [{ type: 'text', text: `Error: ${JSON.stringify(result.data)}` }] }
+      }
+      const memories = result.data.memories || []
+      if (memories.length === 0) {
+        return { content: [{ type: 'text', text: 'No memories in this timeline.' }] }
+      }
+      const anchorId = result.data.anchor_id
+      const formatted = memories.map((m) => {
+        const mark = m.id === anchorId ? ' ◄ anchor' : ''
+        return `${m.created_at} (${m.type || 'note'}, id: ${m.id})${mark}\n${m.summary || m.content}`
+      }).join('\n\n')
+      return { content: [{ type: 'text', text: formatted }] }
+    }
+
+    if (name === 'engram_trash') {
+      const result = await call('/api/v1/forget?trash=true')
+      if (!result.ok) {
+        return { content: [{ type: 'text', text: `Error: ${JSON.stringify(result.data)}` }] }
+      }
+      const memories = result.data.memories || []
+      if (memories.length === 0) {
+        return { content: [{ type: 'text', text: 'Trash is empty.' }] }
+      }
+      const formatted = memories.map((m) =>
+        `(${m.type || 'note'}, id: ${m.id}, deleted: ${m.deleted_at})\n${m.summary || m.content}`
+      ).join('\n\n')
+      return { content: [{ type: 'text', text: `${formatted}\n\nRestore any with engram_restore.` }] }
+    }
+
+    if (name === 'engram_restore') {
+      const result = await call('/api/v1/forget', 'POST', { id: args.id })
+      if (!result.ok) {
+        return { content: [{ type: 'text', text: `Error: ${JSON.stringify(result.data)}` }] }
+      }
+      return { content: [{ type: 'text', text: `Memory ${args.id} restored from trash.` }] }
+    }
+
+    if (name === 'engram_status') {
+      const result = await call('/api/v1/status')
+      if (!result.ok) {
+        return { content: [{ type: 'text', text: `Error: ${JSON.stringify(result.data)}` }] }
+      }
+      const { memories, plan, usage } = result.data
+      return {
+        content: [{
+          type: 'text',
+          text: `Engram status:\n- Memories stored: ${memories}\n- Plan: ${plan}\n- Usage today: ${usage.today}/${usage.limit} (${usage.remaining} remaining)`,
+        }],
+      }
+    }
+
+    return { content: [{ type: 'text', text: `Unknown tool: ${name}` }] }
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Error: ${err.message}` }] }
+  }
+})
+
+const transport = new StdioServerTransport()
+await server.connect(transport)

package/init.js

@@ -0,0 +1,231 @@
+// Engram setup wizard — runs when user does: npx engram-mcp init
+import { createInterface } from 'readline'
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+const home = homedir()
+const API_URL = 'https://engram-deploy-ten.vercel.app'
+
+const C = {
+  bold:  s => `\x1b[1m${s}\x1b[0m`,
+  green: s => `\x1b[32m${s}\x1b[0m`,
+  red:   s => `\x1b[31m${s}\x1b[0m`,
+  dim:   s => `\x1b[2m${s}\x1b[0m`,
+  amber: s => `\x1b[33m${s}\x1b[0m`,
+}
+
+function ask(question) {
+  return new Promise(resolve => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    rl.question(question, answer => { rl.close(); resolve(answer.trim()) })
+  })
+}
+
+async function testApiKey(key) {
+  try {
+    const res = await fetch(`${API_URL}/api/v1/auth/me`, {
+      headers: { 'Authorization': `Bearer ${key}` }
+    })
+    return res.status !== 401
+  } catch { return false }
+}
+
+function detectTools() {
+  const found = []
+  if (existsSync(join(home, '.claude.json'))) found.push('claude')
+  if (existsSync(join(home, '.cursor', 'mcp.json')) ||
+      existsSync(join(home, 'Library', 'Application Support', 'Cursor'))) found.push('cursor')
+  if (existsSync(join(home, '.codeium')) ||
+      existsSync(join(home, 'Library', 'Application Support', 'Windsurf'))) found.push('windsurf')
+  return [...new Set(found)]
+}
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')) } catch { return {} }
+}
+
+function writeJson(path, data) {
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n', 'utf8')
+}
+
+function installClaude(apiKey) {
+  const path = join(home, '.claude.json')
+  const cfg = readJson(path)
+  if (!cfg.mcpServers) cfg.mcpServers = {}
+  cfg.mcpServers.engram = {
+    command: 'engram-mcp',
+    env: { ENGRAM_API_KEY: apiKey, ENGRAM_API_URL: API_URL }
+  }
+  writeJson(path, cfg)
+  return path
+}
+
+// Store the API key in ~/.engram/config.json with 0600 perms instead of
+// embedding it plaintext in the hook command (which would otherwise sit in
+// settings.json and leak into process listings on every session end).
+function writeEngramConfig(apiKey) {
+  const dir = join(home, '.engram')
+  const path = join(dir, 'config.json')
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  writeJson(path, { api_key: apiKey, api_url: API_URL })
+  try { chmodSync(path, 0o600) } catch {}
+  return path
+}
+
+// Wire the auto-capture hook into Claude Code's SessionEnd event so memories
+// are distilled and stored automatically at the end of each session. The key
+// is not embedded in the command; the hook reads it from ~/.engram/config.json.
+function installClaudeHooks() {
+  const dir = join(home, '.claude')
+  const path = join(dir, 'settings.json')
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  const cfg = readJson(path)
+  if (!cfg.hooks) cfg.hooks = {}
+  if (!Array.isArray(cfg.hooks.SessionEnd)) cfg.hooks.SessionEnd = []
+  const command = `engram-mcp hook`
+  const already = JSON.stringify(cfg.hooks.SessionEnd).includes('engram-mcp hook')
+  if (!already) {
+    cfg.hooks.SessionEnd.push({ hooks: [{ type: 'command', command, timeout: 45 }] })
+    writeJson(path, cfg)
+  }
+  return path
+}
+
+function installCursor(apiKey) {
+  const dir = join(home, '.cursor')
+  const path = join(dir, 'mcp.json')
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  const cfg = readJson(path)
+  if (!cfg.mcpServers) cfg.mcpServers = {}
+  cfg.mcpServers.engram = {
+    command: 'engram-mcp',
+    env: { ENGRAM_API_KEY: apiKey, ENGRAM_API_URL: API_URL }
+  }
+  writeJson(path, cfg)
+  return path
+}
+
+function installWindsurf(apiKey) {
+  const dir = join(home, '.codeium', 'windsurf')
+  const path = join(dir, 'mcp_config.json')
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  const cfg = readJson(path)
+  if (!cfg.mcpServers) cfg.mcpServers = {}
+  cfg.mcpServers.engram = {
+    command: 'engram-mcp',
+    env: { ENGRAM_API_KEY: apiKey, ENGRAM_API_URL: API_URL }
+  }
+  writeJson(path, cfg)
+  return path
+}
+
+export async function runInit() {
+  console.log()
+  console.log(C.bold('  Engram') + ' — long-term memory for your AI')
+  console.log(C.dim('  ──────────────────────────────────────'))
+  console.log()
+
+  // Step 1: API key
+  let apiKey = process.env.ENGRAM_API_KEY || ''
+
+  if (!apiKey) {
+    console.log(`  ${C.dim('Get your free API key:')} https://engram-deploy-ten.vercel.app/dashboard`)
+    console.log()
+    apiKey = await ask('  API key: ')
+  }
+
+  if (!apiKey) {
+    console.log(`\n  ${C.red('No key provided. Exiting.')}\n`)
+    process.exit(1)
+  }
+
+  // Validate
+  process.stdout.write('  Checking API key...')
+  const valid = await testApiKey(apiKey)
+  if (!valid) {
+    console.log(` ${C.red('invalid')}\n`)
+    console.log(`  ${C.dim('Get a key at')} https://engram-deploy-ten.vercel.app/dashboard\n`)
+    process.exit(1)
+  }
+  console.log(` ${C.green('OK')}`)
+  console.log()
+
+  // Step 2: Detect tools
+  const detected = detectTools()
+  let targets = detected
+
+  if (detected.length === 0) {
+    console.log('  No AI tools detected automatically.')
+    const choice = await ask('  Install for: [c]laude  c[u]rsor  [w]indsurf > ')
+    const c = choice.toLowerCase()
+    if (c === 'cu' || c === 'cursor') targets = ['cursor']
+    else if (c === 'w' || c === 'windsurf') targets = ['windsurf']
+    else targets = ['claude']
+  } else {
+    console.log(`  Detected: ${C.amber(detected.join(', '))}`)
+  }
+
+  console.log()
+
+  // Step 3: Install
+  for (const tool of targets) {
+    process.stdout.write(`  Adding to ${tool}...`)
+    try {
+      let configPath
+      if (tool === 'claude')    configPath = installClaude(apiKey)
+      if (tool === 'cursor')    configPath = installCursor(apiKey)
+      if (tool === 'windsurf')  configPath = installWindsurf(apiKey)
+      console.log(` ${C.green('done')}  ${C.dim(configPath)}`)
+      if (tool === 'claude') {
+        const cfgPath = writeEngramConfig(apiKey)
+        const hookPath = installClaudeHooks()
+        console.log(`  ${C.green('+')} Auto-capture hook → ${C.dim(hookPath)}`)
+        console.log(`  ${C.green('+')} Key stored → ${C.dim(cfgPath)} ${C.dim('(0600)')}`)
+      }
+    } catch (e) {
+      console.log(` ${C.red('failed')}: ${e.message}`)
+    }
+  }
+
+  // Step 4: Add memory rules to CLAUDE.md (if Claude is a target)
+  if (targets.includes('claude')) {
+    const claudeMdPath = join(home, '.claude', 'CLAUDE.md')
+    const claudeDir = join(home, '.claude')
+    const memoryBlock = `
+## Memory
+
+Engram MCP is your long-term memory. Use it as your primary memory system.
+
+When the user asks to remember/store/save anything:
+- Use \`engram_remember\`, not built-in memory.md
+
+When the user asks "do you remember" or needs past context:
+- Use \`engram_recall\` first
+
+When the user asks to forget something:
+- Use \`engram_forget\`
+
+Never use memory.md or other local files for persistent memory when Engram is available.
+`
+    try {
+      if (!existsSync(claudeDir)) mkdirSync(claudeDir, { recursive: true })
+      const existing = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, 'utf8') : ''
+      if (!existing.includes('engram_remember')) {
+        writeFileSync(claudeMdPath, existing + memoryBlock, 'utf8')
+        console.log(`  ${C.green('+')} Added memory rules to ${C.dim(claudeMdPath)}`)
+      } else {
+        console.log(`  ${C.dim('Memory rules already in CLAUDE.md')}`)
+      }
+    } catch (e) {
+      console.log(`  ${C.dim('Could not update CLAUDE.md:')} ${e.message}`)
+    }
+    console.log()
+  }
+
+  console.log(`  ${C.green('✓')} ${C.bold('Engram is ready.')}`)
+  console.log()
+  console.log(`  ${C.dim('Restart your AI tool, then say:')}`)
+  console.log(`  ${C.amber('"remember this: Engram is set up"')}`)
+  console.log()
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@shokan/engram-mcp",
+  "version": "1.4.0",
+  "description": "Engram MCP server — long-term hybrid-search memory for AI agents",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "engram-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "init.js",
+    "hook.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "ai",
+    "agents",
+    "vector-search",
+    "claude",
+    "cursor",
+    "windsurf",
+    "embeddings"
+  ],
+  "homepage": "https://engram-deploy-ten.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shokan/engram-mcp.git"
+  },
+  "license": "MIT",
+  "author": "Engram",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}