persyst-mcp 2.0.0 → 2.1.0

package/bin/aider.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+
+/**
+ * persyst-aider — Aider wrapper with automatic Persyst memory injection
+ * 
+ * Usage:
+ *   npx persyst-aider [aider-args...]
+ * 
+ * Examples:
+ *   npx persyst-aider --model anthropic/claude-sonnet-4
+ *   npx persyst-aider --model openai/gpt-4o --auto-commits
+ * 
+ * How it works:
+ *   1. On startup: connects to Persyst, ingests recent git commits
+ *   2. Before each prompt: queries Persyst for relevant memories, prepends context
+ *   3. On exit: ingests any new git commits created during the session
+ * 
+ * Design decisions:
+ *   - Only enriches prompts > 15 chars (skip "y", "ok", "/run", etc.)
+ *   - Does NOT parse Aider's output (too fragile with ANSI codes, streaming, etc.)
+ *   - Passes all args directly to Aider — fully transparent proxy
+ */
+
+import { spawn } from 'child_process';
+import { createInterface } from 'readline';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const MIN_PROMPT_LENGTH = 15;
+const CWD = process.cwd();
+
+// ============================================================
+// MCP CLIENT
+// ============================================================
+
+let persystClient = null;
+
+async function connectToPersyst() {
+  if (persystClient) return persystClient;
+
+  const persystPath = resolve(__dirname, '..', 'index.js');
+
+  const transport = new StdioClientTransport({
+    command: 'node',
+    args: [persystPath]
+  });
+
+  persystClient = new Client({
+    name: 'persyst-aider',
+    version: '1.0.0'
+  });
+
+  await persystClient.connect(transport);
+  return persystClient;
+}
+
+async function callTool(toolName, args) {
+  const client = await connectToPersyst();
+  const result = await client.callTool({ name: toolName, arguments: args });
+  if (result.content && result.content[0] && result.content[0].text) {
+    return JSON.parse(result.content[0].text);
+  }
+  return null;
+}
+
+async function closePersyst() {
+  if (persystClient) {
+    try { await persystClient.close(); } catch (_) {}
+    persystClient = null;
+  }
+}
+
+// ============================================================
+// MEMORY FUNCTIONS
+// ============================================================
+
+/**
+ * Ingest recent git commits from the current directory.
+ */
+async function ingestGitCommits() {
+  try {
+    const result = await callTool('ingest_git_commits', {
+      repo_path: CWD,
+      count: 15
+    });
+    if (result && result.added > 0) {
+      console.error(`[persyst] Ingested ${result.added} git commits into memory`);
+    }
+  } catch (_) {
+    // Not a git repo or Persyst unavailable — silent
+  }
+}
+
+/**
+ * Search for memories relevant to the user's prompt.
+ * Returns a formatted context string or null.
+ */
+async function getMemoryContext(prompt) {
+  try {
+    const result = await callTool('search_memories', {
+      query: prompt.slice(0, 200),
+      limit: 5,
+      agent_id: 'aider'
+    });
+
+    if (!result || !result.results || result.results.length === 0) {
+      return null;
+    }
+
+    const lines = ['[Persyst Memory — auto-retrieved context]'];
+    for (const mem of result.results) {
+      lines.push(`• ${mem.content}`);
+    }
+    lines.push('[End Memory]');
+    lines.push('');
+
+    return lines.join('\n');
+  } catch (_) {
+    return null;
+  }
+}
+
+// ============================================================
+// MAIN
+// ============================================================
+
+async function main() {
+  const aiderArgs = process.argv.slice(2);
+
+  // Check if Aider is available
+  console.error('[persyst] Starting Aider with Persyst memory...');
+
+  // Step 1: Connect to Persyst and ingest git history
+  try {
+    await connectToPersyst();
+    console.error('[persyst] Connected to memory server ✓');
+    await ingestGitCommits();
+  } catch (err) {
+    console.error(`[persyst] Warning: Could not connect to memory server: ${err.message}`);
+    console.error('[persyst] Aider will run without memory injection.');
+  }
+
+  // Step 2: Spawn Aider as a child process
+  const aider = spawn('aider', aiderArgs, {
+    stdio: ['pipe', 'inherit', 'inherit'],
+    shell: true,
+    cwd: CWD
+  });
+
+  // Step 3: Set up stdin interception
+  const rl = createInterface({
+    input: process.stdin,
+    terminal: false
+  });
+
+  rl.on('line', async (line) => {
+    const trimmed = line.trim();
+
+    // Only enrich prompts that are long enough to be real questions
+    if (trimmed.length >= MIN_PROMPT_LENGTH && persystClient) {
+      try {
+        const context = await getMemoryContext(trimmed);
+        if (context) {
+          // Prepend memory context to the prompt
+          aider.stdin.write(context);
+          console.error(`[persyst] Injected ${context.split('\n').length - 3} memories`);
+        }
+      } catch (_) {
+        // Memory injection failed — just pass through the original prompt
+      }
+    }
+
+    // Always forward the original line to Aider
+    aider.stdin.write(line + '\n');
+  });
+
+  // Handle user Ctrl+C
+  process.on('SIGINT', () => {
+    aider.kill('SIGINT');
+  });
+
+  // Step 4: On Aider exit, ingest any new commits and clean up
+  aider.on('close', async (code) => {
+    console.error('[persyst] Aider session ended. Indexing new commits...');
+    await ingestGitCommits();
+    await closePersyst();
+    process.exit(code || 0);
+  });
+
+  // Handle stdin close (user closed terminal)
+  rl.on('close', () => {
+    aider.stdin.end();
+  });
+}
+
+main().catch(err => {
+  console.error(`[persyst] Fatal error: ${err.message}`);
+  process.exit(1);
+});

package/bin/setup.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+/**
+ * persyst-setup — One-command installer for Persyst Claude Code hooks
+ * 
+ * Usage:
+ *   npx persyst-mcp setup
+ * 
+ * What it does:
+ *   1. Copies persyst-hook.js to ~/.persyst/hooks/
+ *   2. Creates or merges ~/.claude/settings.json with hook registrations
+ *   3. Prints success message with instructions
+ * 
+ * Design:
+ *   - Non-destructive: merges with existing settings, never overwrites
+ *   - Cross-platform: works on Windows, macOS, and Linux
+ *   - Idempotent: safe to run multiple times
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ============================================================
+// PATHS
+// ============================================================
+
+const HOME = homedir();
+const PERSYST_DIR = join(HOME, '.persyst');
+const PERSYST_HOOKS_DIR = join(PERSYST_DIR, 'hooks');
+const HOOK_DEST = join(PERSYST_HOOKS_DIR, 'persyst-hook.js');
+
+const CLAUDE_DIR = join(HOME, '.claude');
+const CLAUDE_SETTINGS = join(CLAUDE_DIR, 'settings.json');
+
+// Source hook file — shipped with the npm package
+const HOOK_SOURCE = resolve(__dirname, '..', 'hooks', 'persyst-hook.js');
+
+// ============================================================
+// HOOK CONFIGURATION
+// ============================================================
+
+const HOOK_ENTRY = {
+  type: 'command',
+  command: `node "${HOOK_DEST}"`
+};
+
+const HOOK_CONFIG = {
+  SessionStart: [
+    {
+      matcher: '',
+      hooks: [{ ...HOOK_ENTRY }]
+    }
+  ],
+  UserPromptSubmit: [
+    {
+      matcher: '',
+      hooks: [{ ...HOOK_ENTRY, timeout: 10 }]
+    }
+  ]
+};
+
+// ============================================================
+// HELPERS
+// ============================================================
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function readJsonFile(filePath) {
+  try {
+    const raw = readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Merge Persyst hook entries into existing settings.
+ * Does NOT overwrite existing hooks — appends Persyst entries if not already present.
+ */
+function mergeHookSettings(existing) {
+  const settings = { ...existing };
+  if (!settings.hooks) {
+    settings.hooks = {};
+  }
+
+  for (const [eventName, hookGroups] of Object.entries(HOOK_CONFIG)) {
+    if (!settings.hooks[eventName]) {
+      settings.hooks[eventName] = [];
+    }
+
+    // Check if a Persyst hook is already registered
+    const alreadyRegistered = settings.hooks[eventName].some(group =>
+      group.hooks && group.hooks.some(h =>
+        h.command && h.command.includes('persyst-hook')
+      )
+    );
+
+    if (!alreadyRegistered) {
+      settings.hooks[eventName].push(...hookGroups);
+    }
+  }
+
+  return settings;
+}
+
+// ============================================================
+// MAIN
+// ============================================================
+
+function run() {
+  console.log('');
+  console.log('  🧠 Persyst — Claude Code Hook Setup');
+  console.log('  ════════════════════════════════════');
+  console.log('');
+
+  // Step 1: Verify hook source exists
+  if (!existsSync(HOOK_SOURCE)) {
+    console.error(`  ❌ Hook source not found at: ${HOOK_SOURCE}`);
+    console.error('     Make sure you are running this from the persyst-mcp package.');
+    process.exit(1);
+  }
+
+  // Step 2: Copy hook file to ~/.persyst/hooks/
+  console.log('  📁 Installing hook script...');
+  ensureDir(PERSYST_HOOKS_DIR);
+  copyFileSync(HOOK_SOURCE, HOOK_DEST);
+  console.log(`     ✅ Copied to ${HOOK_DEST}`);
+
+  // Step 3: Merge into ~/.claude/settings.json
+  console.log('');
+  console.log('  ⚙️  Configuring Claude Code...');
+  ensureDir(CLAUDE_DIR);
+
+  const existingSettings = readJsonFile(CLAUDE_SETTINGS);
+  const mergedSettings = mergeHookSettings(existingSettings);
+
+  writeFileSync(CLAUDE_SETTINGS, JSON.stringify(mergedSettings, null, 2) + '\n', 'utf8');
+  console.log(`     ✅ Updated ${CLAUDE_SETTINGS}`);
+
+  // Step 4: Print success
+  console.log('');
+  console.log('  ════════════════════════════════════');
+  console.log('  ✅ Setup complete!');
+  console.log('');
+  console.log('  Persyst will now automatically:');
+  console.log('    • Load your stored memories when Claude Code starts');
+  console.log('    • Search for relevant context on every prompt');
+  console.log('    • Index your git commits into the memory database');
+  console.log('');
+  console.log('  ⚡ Restart Claude Code to activate the hooks.');
+  console.log('');
+  console.log('  Memory database: ~/.persyst/persyst.db');
+  console.log('  Hook script:     ~/.persyst/hooks/persyst-hook.js');
+  console.log('  Claude settings:  ~/.claude/settings.json');
+  console.log('');
+}
+
+run();

package/hooks/persyst-hook.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+
+/**
+ * persyst-hook.js — Claude Code Hook for Persyst Memory
+ * 
+ * Automatically injects relevant memories into Claude Code's context
+ * on SessionStart and UserPromptSubmit events.
+ * 
+ * How it works:
+ *   1. Claude Code sends a JSON payload on stdin with hook_event_name, session_id, cwd, etc.
+ *   2. This script connects to the Persyst MCP server via StdioClientTransport.
+ *   3. It calls get_optimized_context or search_memories to retrieve relevant memories.
+ *   4. It returns a JSON response on stdout with additionalContext for Claude Code to inject.
+ * 
+ * Installation:
+ *   npx persyst-mcp setup
+ * 
+ * Manual registration in ~/.claude/settings.json:
+ *   { "hooks": { "SessionStart": [...], "UserPromptSubmit": [...] } }
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Minimum prompt length to trigger memory search (skip "y", "ok", "/run", etc.)
+const MIN_PROMPT_LENGTH = 15;
+
+// Maximum time to wait for Persyst MCP connection (ms)
+const CONNECTION_TIMEOUT = 8000;
+
+/**
+ * Read the full JSON payload from stdin.
+ * Claude Code sends the hook context as a single JSON object.
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { data += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        resolve(JSON.parse(data));
+      } catch (e) {
+        reject(new Error(`Failed to parse stdin JSON: ${e.message}`));
+      }
+    });
+    process.stdin.on('error', reject);
+  });
+}
+
+/**
+ * Connect to the Persyst MCP server as a client.
+ * Uses StdioClientTransport to spawn and communicate with the server.
+ */
+async function connectToPersyst() {
+  // Resolve the path to Persyst's index.js relative to this hook file
+  const persystPath = resolve(__dirname, '..', 'index.js');
+
+  const transport = new StdioClientTransport({
+    command: 'node',
+    args: [persystPath]
+  });
+
+  const client = new Client({
+    name: 'persyst-hook',
+    version: '1.0.0'
+  });
+
+  // Connect with a timeout
+  await Promise.race([
+    client.connect(transport),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('Persyst connection timeout')), CONNECTION_TIMEOUT)
+    )
+  ]);
+
+  return client;
+}
+
+/**
+ * Call a Persyst MCP tool and parse the JSON result.
+ */
+async function callTool(client, toolName, args) {
+  const result = await client.callTool({ name: toolName, arguments: args });
+  if (result.content && result.content[0] && result.content[0].text) {
+    return JSON.parse(result.content[0].text);
+  }
+  return null;
+}
+
+/**
+ * Handle SessionStart: load project-wide context and ingest git history.
+ */
+async function handleSessionStart(client, input) {
+  const cwd = input.cwd || process.cwd();
+  const repoName = cwd.replace(/\\/g, '/').split('/').pop();
+
+  // 1. Get project-wide memory context
+  const contextResult = await callTool(client, 'get_optimized_context', {
+    query: `Project ${repoName} conventions, architecture, user preferences, coding rules`,
+    max_tokens: 2000,
+    agent_id: 'claude-code',
+    session_id: input.session_id || undefined
+  });
+
+  // 2. Ingest recent git commits (best-effort, don't fail if not a git repo)
+  try {
+    await callTool(client, 'ingest_git_commits', {
+      repo_path: cwd,
+      count: 15
+    });
+  } catch (_) {
+    // Not a git repo or git not available — that's fine
+  }
+
+  // 3. Build the additional context string
+  let additionalContext = '';
+  if (contextResult && contextResult.context) {
+    additionalContext = contextResult.context;
+  }
+
+  // 4. Get memory count for status line
+  let memoryCount = 0;
+  try {
+    const recentResult = await callTool(client, 'get_recent_memories', { limit: 1 });
+    if (recentResult && recentResult.count !== undefined) {
+      // The count from get_recent is just the returned count, not total
+      // Use a search to estimate total active memories
+      const importantResult = await callTool(client, 'get_important_memories', { limit: 100 });
+      memoryCount = importantResult?.count || 0;
+    }
+  } catch (_) {
+    // Non-critical
+  }
+
+  if (additionalContext) {
+    additionalContext = `[Persyst Memory: ${memoryCount} memories loaded for project "${repoName}"]\n${additionalContext}`;
+  }
+
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: additionalContext || undefined
+    }
+  };
+}
+
+/**
+ * Handle UserPromptSubmit: search for memories relevant to the user's prompt.
+ */
+async function handleUserPromptSubmit(client, input) {
+  const prompt = input.prompt || '';
+
+  // Skip trivial prompts (commands, confirmations, short inputs)
+  if (prompt.trim().length < MIN_PROMPT_LENGTH) {
+    return {};
+  }
+
+  // Use search_memories for speed on per-prompt lookups (faster than get_optimized_context)
+  const searchResult = await callTool(client, 'search_memories', {
+    query: prompt.slice(0, 200), // Truncate very long prompts for search efficiency
+    limit: 5,
+    agent_id: 'claude-code',
+    session_id: input.session_id || undefined
+  });
+
+  if (!searchResult || !searchResult.results || searchResult.results.length === 0) {
+    return {};
+  }
+
+  // Format memories as context
+  let contextLines = ['=== PERSYST MEMORY (auto-retrieved) ==='];
+  for (const mem of searchResult.results) {
+    contextLines.push(`• [Memory #${mem.id}] ${mem.content}`);
+  }
+  contextLines.push('=== END MEMORY ===');
+
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: contextLines.join('\n')
+    }
+  };
+}
+
+/**
+ * Main entry point.
+ */
+async function main() {
+  let client = null;
+
+  try {
+    const input = await readStdin();
+    const eventName = input.hook_event_name;
+
+    // Only handle events we care about
+    if (eventName !== 'SessionStart' && eventName !== 'UserPromptSubmit') {
+      console.log(JSON.stringify({}));
+      return;
+    }
+
+    // Connect to Persyst
+    client = await connectToPersyst();
+
+    let response;
+    if (eventName === 'SessionStart') {
+      response = await handleSessionStart(client, input);
+    } else if (eventName === 'UserPromptSubmit') {
+      response = await handleUserPromptSubmit(client, input);
+    } else {
+      response = {};
+    }
+
+    console.log(JSON.stringify(response));
+
+  } catch (err) {
+    // Hooks must NEVER break Claude Code — always fail silently
+    console.error(`[persyst-hook] Error: ${err.message}`);
+    console.log(JSON.stringify({}));
+  } finally {
+    // Clean up MCP connection
+    if (client) {
+      try { await client.close(); } catch (_) {}
+    }
+    process.exit(0);
+  }
+}
+
+main();

package/index.js

@@ -7,14 +7,23 @@
  * Starts the MCP server on stdio transport.
  * 
  * Usage:
- *   node index.js          (direct)
- *   npx persyst-mcp        (via npm)
+ *   node index.js          (direct — starts MCP server)
+ *   npx persyst-mcp        (via npm — starts MCP server)
+ *   npx persyst-mcp setup  (install Claude Code hooks)
  *   persyst-mcp            (if installed globally)
  */
 
-import { startServer } from './src/server.js';
+// Handle subcommands before starting the server
+const subcommand = process.argv[2];
 
-await startServer().catch(err => {
-  console.error('❌ Persyst failed to start:', err.message);
-  process.exit(1);
-});
+if (subcommand === 'setup') {
+  // Delegate to the setup CLI
+  await import('./bin/setup.js');
+} else {
+  // Default: start the MCP server
+  const { startServer } = await import('./src/server.js');
+  await startServer().catch(err => {
+    console.error('❌ Persyst failed to start:', err.message);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "persyst-mcp",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Local-first MCP memory server with hybrid keyword + semantic search for coding agents",
   "type": "module",
   "main": "index.js",
   "bin": {
-    "persyst-mcp": "index.js"
+    "persyst-mcp": "index.js",
+    "persyst-setup": "bin/setup.js",
+    "persyst-aider": "bin/aider.js"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -13,6 +15,8 @@
   "files": [
     "index.js",
     "src/",
+    "bin/",
+    "hooks/",
     "README.md",
     "LICENSE"
   ],

package/src/search.js

@@ -64,8 +64,8 @@ export async function searchHybrid(queryText, limit = 5, agentId = null, session
         keyword_match: isKeywordMatch
       };
     })
-    // Filter out low similarity semantic matches if they have no keyword match (threshold 0.35)
-    .filter(r => r.keyword_match || r.similarity >= 0.35);
+    // Filter out low similarity semantic matches if they have no keyword match (threshold 0.30)
+    .filter(r => r.keyword_match || r.similarity >= 0.30);
 
   // Add keyword-only hits that semantic search missed
   const semanticIds = new Set(semanticResults.map(r => r.id));

package/src/server.js

@@ -23,7 +23,7 @@ export async function startServer() {
   // --- Create MCP server ---
   const server = new McpServer({
     name: 'persyst',
-    version: '2.0.0'
+    version: '2.1.0'
   });
 
   // --- Register all tools ---