persyst-mcp 2.1.0 → 2.1.2

package/bin/init.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+/**
+ * persyst-init — Workspace rules generator for VS Code-based IDEs (Cursor, Windsurf, Antigravity)
+ * 
+ * Usage:
+ *   npx persyst-mcp init
+ * 
+ * What it does:
+ *   1. Safely creates or appends system instructions to `.cursorrules`
+ *   2. Safely creates or appends system instructions to `.windsurfrules`
+ *   3. Creates a general `.persystrules.md` copy-pasteable guide
+ *   4. Prints instructions on configuring MCP servers in Cursor/VS Code/Antigravity
+ * 
+ * Design:
+ *   - Non-destructive: checks for existing content before appending to avoid duplication
+ *   - Idempotent: safe to run multiple times
+ *   - Localized: targets the current working directory (project root)
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ============================================================
+// SYSTEM INSTRUCTION CONTENT
+// ============================================================
+
+const INSTRUCTION_HEADER = '# Persyst Memory Integration';
+
+const RULE_CONTENT = `
+${INSTRUCTION_HEADER}
+You are integrated with Persyst, a local-first MCP memory server that stores user preferences, project guidelines, context, and decisions.
+
+## Proactive Memory Retrieval (CRITICAL)
+- Before responding to the user's prompt or executing any task, you MUST invoke the \`persyst\` MCP server's \`search_memories\` or \`get_optimized_context\` tool.
+- Extract relevant search terms from the user's prompt (e.g. if the user says "update the database schema", query "database", "schema", "sqlite", "table").
+- Provide your agent name (e.g. \`cursor-agent\`, \`roo-code\`) as the \`agent_id\` parameter when searching to query your private namespace + shared project context.
+
+## Proactive Memory Storage (CRITICAL)
+- Record Milestones: When you successfully implement a feature, fix a bug, or make an architectural decision, call the \`add_memory\` tool to store a summary of the change.
+- Agentic Swarms & Namespaces: If you are part of a multi-agent swarm or need private partition, pass your agent name as \`agent_id\` and set \`shared: false\` to store private memories. For general project guidelines and files, leave \`shared: true\` (default) so other agents can access them.
+- Handle Contradictions: Persyst handles contradiction detection automatically. If a new fact contradicts an old memory, Persyst will flag it.
+- Quality Over Quantity: Do NOT store trivial facts, temporary conversation noise, or duplicate data. "Bad data is worse than no data". Only store long-term architecture decisions, project details, and explicit user preferences.
+`;
+
+const GENERAL_GUIDE = `# Persyst General Agent Integration Guide
+
+This workspace is configured with the Persyst local-first memory server.
+
+## How to Configure the MCP Server in VS Code / Cursor / Antigravity
+
+Add the following configuration to your IDE's MCP Server settings:
+
+- **Server Name:** \`persyst\`
+- **Type:** \`command\`
+- **Command:** \`npx\`
+- **Arguments:** \`["-y", "persyst-mcp"]\`
+
+Alternatively, if you have installed the package globally (\`npm install -g persyst-mcp\`), you can configure:
+- **Command:** \`persyst-mcp\`
+- **Arguments:** \`[]\`
+
+---
+
+## Copy-Paste System Prompt Instructions
+If your agent does not read \`.cursorrules\` or \`.windsurfrules\` natively, copy and paste the following prompt into the agent's Custom Instructions, System Prompt, or System Rules:
+
+\`\`\`markdown
+${RULE_CONTENT.trim()}
+\`\`\`
+`;
+
+// ============================================================
+// HELPERS
+// ============================================================
+
+function setupRuleFile(filePath, fileName) {
+  let content = RULE_CONTENT;
+  let action = 'Created';
+
+  if (existsSync(filePath)) {
+    const existing = readFileSync(filePath, 'utf8');
+    if (existing.includes(INSTRUCTION_HEADER)) {
+      console.log(`     ℹ️  ${fileName} already has Persyst rules configured (skipped).`);
+      return;
+    }
+    content = existing + '\n' + RULE_CONTENT;
+    action = 'Appended to';
+  }
+
+  writeFileSync(filePath, content.trim() + '\n', 'utf8');
+  console.log(`     ✅ ${action} ${fileName}`);
+}
+
+// ============================================================
+// MAIN
+// ============================================================
+
+function run() {
+  console.log('');
+  console.log('  🧠 Persyst — Workspace Rules Setup');
+  console.log('  ════════════════════════════════════');
+  console.log('');
+
+  const cwd = process.cwd();
+  console.log(`  📁 Target workspace: ${cwd}`);
+  console.log('');
+
+  // 1. Create/Append Cursor Rules
+  const cursorRulesPath = join(cwd, '.cursorrules');
+  setupRuleFile(cursorRulesPath, '.cursorrules');
+
+  // 2. Create/Append Windsurf Rules
+  const windsurfRulesPath = join(cwd, '.windsurfrules');
+  setupRuleFile(windsurfRulesPath, '.windsurfrules');
+
+  // 3. Create General Guide File
+  const generalGuidePath = join(cwd, '.persystrules.md');
+  writeFileSync(generalGuidePath, GENERAL_GUIDE.trim() + '\n', 'utf8');
+  console.log('     ✅ Created .persystrules.md (General Guide)');
+
+  // 4. Configure Git post-commit hook for automatic commit ingestion
+  const gitDir = join(cwd, '.git');
+  if (existsSync(gitDir)) {
+    const hooksDir = join(gitDir, 'hooks');
+    mkdirSync(hooksDir, { recursive: true });
+    const postCommitPath = join(hooksDir, 'post-commit');
+    const localPersystPath = resolve(__dirname, '..', 'index.js').replace(/\\/g, '/');
+
+    const hookContent = `#!/bin/sh
+# Persyst Git Commit Ingestion Hook
+# Automatically ingests recent commits into Persyst memory on every commit.
+
+# Local project path fallback for development
+LOCAL_PERSYST="${localPersystPath}"
+
+if [ -f "$LOCAL_PERSYST" ]; then
+  node "$LOCAL_PERSYST" ingest "$PWD" 5 >/dev/null 2>&1 || true
+else
+  npx persyst-mcp ingest "$PWD" 5 >/dev/null 2>&1 || true
+fi
+`;
+
+    writeFileSync(postCommitPath, hookContent, { mode: 0o755 });
+    try {
+      chmodSync(postCommitPath, 0o755);
+    } catch (_) {}
+    console.log('     ✅ Configured Git post-commit hook for auto-ingestion');
+  }
+
+  // 5. Print Success & Configuration Help
+  console.log('');
+  console.log('  ════════════════════════════════════');
+  console.log('  ✅ Rules and Git hooks initialization complete!');
+  console.log('');
+  console.log('  To connect the memory server to Cursor, Antigravity, or VS Code:');
+  console.log('    1. Open your IDE Settings -> MCP (Model Context Protocol).');
+  console.log('    2. Add a new command server:');
+  console.log('         • Name:      persyst');
+  console.log('         • Command:   npx');
+  console.log('         • Arguments: -y persyst-mcp');
+  console.log('');
+  console.log('  The rules we generated will guide the AI agents in this workspace to:');
+  console.log('    • Proactively search memory before answering prompts.');
+  console.log('    • Log milestone achievements and user preferences.');
+  console.log('    • Keep the memory clean ("no bad data").');
+  console.log('');
+}
+
+run();

package/bin/setup.js

@@ -130,11 +130,16 @@ function run() {
     process.exit(1);
   }
 
-  // Step 2: Copy hook file to ~/.persyst/hooks/
-  console.log('  📁 Installing hook script...');
+  // Step 2: Copy and template hook file to ~/.persyst/hooks/
+  console.log('  📁 Installing and templating hook script...');
   ensureDir(PERSYST_HOOKS_DIR);
-  copyFileSync(HOOK_SOURCE, HOOK_DEST);
-  console.log(`     ✅ Copied to ${HOOK_DEST}`);
+  const INDEX_PATH = resolve(__dirname, '..', 'index.js');
+  const WORKER_PATH = resolve(__dirname, '..', 'bin', 'extract-worker.js');
+  let hookContent = readFileSync(HOOK_SOURCE, 'utf8');
+  hookContent = hookContent.replace('{{PERSYST_INDEX_PATH}}', INDEX_PATH.replace(/\\/g, '/'));
+  hookContent = hookContent.replace('{{PERSYST_WORKER_PATH}}', WORKER_PATH.replace(/\\/g, '/'));
+  writeFileSync(HOOK_DEST, hookContent, 'utf8');
+  console.log(`     ✅ Copied & templated to ${HOOK_DEST}`);
 
   // Step 3: Merge into ~/.claude/settings.json
   console.log('');

package/hooks/persyst-hook.js

@@ -1,38 +1,66 @@
 #!/usr/bin/env node
 
 /**
- * persyst-hook.js — Claude Code Hook for Persyst Memory
+ * persyst-hook.js — Claude Code Hook for Persyst Memory (PAMP-Enhanced)
  * 
  * Automatically injects relevant memories into Claude Code's context
- * on SessionStart and UserPromptSubmit events.
+ * on SessionStart and UserPromptSubmit events, and queues conversation
+ * turns for async background extraction on Stop events.
+ * 
+ * PAMP Integration (Persyst Auto-Memory Pipeline):
+ *   - Tier 1: Agent-explicit add_memory calls (existing, unchanged)
+ *   - Tier 2: Heuristic regex extraction on UserPromptSubmit (sync, zero-cost)
+ *   - Tier 3: Async LLM extraction via background worker (spawned on Stop)
  * 
  * How it works:
- *   1. Claude Code sends a JSON payload on stdin with hook_event_name, session_id, cwd, etc.
+ *   1. Claude Code sends a JSON payload on stdin with hook_event_name, session_id, 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.
+ *   5. On Stop: queues the conversation text for background LLM extraction.
  * 
  * Installation:
  *   npx persyst-mcp setup
  * 
  * Manual registration in ~/.claude/settings.json:
- *   { "hooks": { "SessionStart": [...], "UserPromptSubmit": [...] } }
+ *   { "hooks": { "SessionStart": [...], "UserPromptSubmit": [...], "Stop": [...] } }
  */
 
 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';
+import { dirname, resolve, join } from 'path';
+import { spawn } from 'child_process';
+import { writeFileSync, readdirSync, mkdirSync, existsSync } from 'fs';
+import { homedir } from 'os';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+// ============================================================
+// CONFIGURATION
+// ============================================================
+
 // 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;
 
+// Hard timeout for the entire hook execution (ms)
+// Claude Code will kill the hook if it exceeds this
+const MAX_HOOK_LATENCY_MS = 500;
+
+// Maximum active queue jobs before skipping worker spawn
+const MAX_QUEUE_JOBS = 20;
+
+// Queue directory for background extraction jobs
+const QUEUE_DIR = join(homedir(), '.persyst', 'queue');
+
+// ============================================================
+// STDIN READER
+// ============================================================
+
 /**
  * Read the full JSON payload from stdin.
  * Claude Code sends the hook context as a single JSON object.
@@ -53,13 +81,20 @@ function readStdin() {
   });
 }
 
+// ============================================================
+// MCP CLIENT CONNECTION
+// ============================================================
+
 /**
  * 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');
+  // Resolve the path to Persyst's index.js
+  let persystPath = '{{PERSYST_INDEX_PATH}}';
+  if (persystPath.startsWith('{{')) {
+    persystPath = resolve(__dirname, '..', 'index.js');
+  }
 
   const transport = new StdioClientTransport({
     command: 'node',
@@ -93,6 +128,89 @@ async function callTool(client, toolName, args) {
   return null;
 }
 
+// ============================================================
+// PAMP: QUEUE MANAGEMENT
+// ============================================================
+
+/**
+ * Count active job files in the queue directory.
+ * Used for worker pool protection — don't spawn if overloaded.
+ * @returns {number}
+ */
+function countQueueJobs() {
+  try {
+    if (!existsSync(QUEUE_DIR)) return 0;
+    return readdirSync(QUEUE_DIR).filter(f => f.endsWith('.json')).length;
+  } catch (_) {
+    return 0;
+  }
+}
+
+/**
+ * Write a conversation turn to the extraction queue.
+ * @param {string} text - The conversation text to extract from
+ * @param {Object} meta - Metadata (session_id, agent_id, etc.)
+ */
+function enqueueJob(text, meta = {}) {
+  try {
+    mkdirSync(QUEUE_DIR, { recursive: true });
+
+    const jobId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const jobFile = join(QUEUE_DIR, `${jobId}.json`);
+
+    writeFileSync(jobFile, JSON.stringify({
+      text,
+      session_id: meta.session_id || null,
+      agent_id: meta.agent_id || 'claude-code',
+      namespace: meta.namespace || 'shared',
+      cwd: meta.cwd || null,
+      queued_at: new Date().toISOString(),
+      _retries: 0
+    }, null, 2));
+
+    return jobId;
+  } catch (err) {
+    // Non-critical — log and continue
+    process.stderr.write(`[persyst-hook] Queue write failed: ${err.message}\n`);
+    return null;
+  }
+}
+
+/**
+ * Spawn the background extraction worker as a detached process.
+ * The worker runs independently — hook doesn't wait for it.
+ */
+function spawnWorker() {
+  // Check queue depth first
+  const queueDepth = countQueueJobs();
+  if (queueDepth > MAX_QUEUE_JOBS) {
+    process.stderr.write(`[persyst-hook] Queue overloaded (${queueDepth} jobs), skipping worker spawn.\n`);
+    return;
+  }
+
+  try {
+    let workerPath = '{{PERSYST_WORKER_PATH}}';
+    if (workerPath.startsWith('{{')) {
+      workerPath = resolve(__dirname, '..', 'bin', 'extract-worker.js');
+    }
+
+    const child = spawn('node', [workerPath], {
+      detached: true,
+      stdio: 'ignore',
+      env: { ...process.env }
+    });
+
+    // Unref so the hook can exit without waiting for the worker
+    child.unref();
+  } catch (err) {
+    process.stderr.write(`[persyst-hook] Worker spawn failed: ${err.message}\n`);
+  }
+}
+
+// ============================================================
+// EVENT HANDLERS
+// ============================================================
+
 /**
  * Handle SessionStart: load project-wide context and ingest git history.
  */
@@ -152,6 +270,7 @@ async function handleSessionStart(client, input) {
 
 /**
  * Handle UserPromptSubmit: search for memories relevant to the user's prompt.
+ * Also runs Tier 2 heuristic extraction inline (zero-cost).
  */
 async function handleUserPromptSubmit(client, input) {
   const prompt = input.prompt || '';
@@ -161,6 +280,25 @@ async function handleUserPromptSubmit(client, input) {
     return {};
   }
 
+  // --- Tier 2: Run heuristic extraction inline (sync, zero-cost) ---
+  // We don't store results here — we queue them alongside the LLM job.
+  // This just detects if there's extractable signal in the prompt.
+  let heuristicFacts = [];
+  try {
+    const { extractHeuristic } = await import('../src/extractor-heuristic.js');
+    heuristicFacts = extractHeuristic(prompt);
+  } catch (_) {
+    // Heuristic module not available — Tier 3 will handle it
+  }
+
+  // Queue the prompt for Tier 3 background extraction (non-blocking)
+  enqueueJob(prompt, {
+    session_id: input.session_id,
+    agent_id: 'claude-code',
+    cwd: input.cwd
+  });
+
+  // --- Memory Retrieval (existing behavior) ---
   // 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
@@ -178,6 +316,13 @@ async function handleUserPromptSubmit(client, input) {
   for (const mem of searchResult.results) {
     contextLines.push(`• [Memory #${mem.id}] ${mem.content}`);
   }
+
+  // Add heuristic extraction notice if any facts were detected
+  if (heuristicFacts.length > 0) {
+    contextLines.push('');
+    contextLines.push(`[PAMP: ${heuristicFacts.length} fact signal(s) detected, queued for extraction]`);
+  }
+
   contextLines.push('=== END MEMORY ===');
 
   return {
@@ -189,8 +334,31 @@ async function handleUserPromptSubmit(client, input) {
 }
 
 /**
- * Main entry point.
+ * Handle Stop: queue the final conversation turn for background extraction
+ * and spawn the worker to process the queue.
  */
+async function handleStop(input) {
+  // The Stop event may include conversation_turns or transcript data
+  const transcript = input.transcript || input.conversation || '';
+
+  if (transcript && typeof transcript === 'string' && transcript.length > MIN_PROMPT_LENGTH) {
+    enqueueJob(transcript, {
+      session_id: input.session_id,
+      agent_id: 'claude-code',
+      cwd: input.cwd
+    });
+  }
+
+  // Spawn background worker to process all queued jobs
+  spawnWorker();
+
+  return {};
+}
+
+// ============================================================
+// MAIN ENTRY POINT
+// ============================================================
+
 async function main() {
   let client = null;
 
@@ -198,20 +366,37 @@ async function main() {
     const input = await readStdin();
     const eventName = input.hook_event_name;
 
+    // Handle Stop event without MCP connection (just queue + spawn)
+    if (eventName === 'Stop') {
+      const response = await handleStop(input);
+      console.log(JSON.stringify(response));
+      return;
+    }
+
     // Only handle events we care about
     if (eventName !== 'SessionStart' && eventName !== 'UserPromptSubmit') {
       console.log(JSON.stringify({}));
       return;
     }
 
-    // Connect to Persyst
+    // Connect to Persyst with hard timeout
+    const hookStart = Date.now();
     client = await connectToPersyst();
 
     let response;
     if (eventName === 'SessionStart') {
       response = await handleSessionStart(client, input);
     } else if (eventName === 'UserPromptSubmit') {
-      response = await handleUserPromptSubmit(client, input);
+      // Apply hard timeout for prompt-time hook execution
+      response = await Promise.race([
+        handleUserPromptSubmit(client, input),
+        new Promise((resolve) =>
+          setTimeout(() => {
+            process.stderr.write(`[persyst-hook] UserPromptSubmit hit ${MAX_HOOK_LATENCY_MS}ms timeout, returning partial.\n`);
+            resolve({});
+          }, MAX_HOOK_LATENCY_MS - (Date.now() - hookStart))
+        )
+      ]);
     } else {
       response = {};
     }

package/index.js

@@ -10,6 +10,8 @@
  *   node index.js          (direct — starts MCP server)
  *   npx persyst-mcp        (via npm — starts MCP server)
  *   npx persyst-mcp setup  (install Claude Code hooks)
+ *   npx persyst-mcp init   (initialize workspace rules & git hooks)
+ *   npx persyst-mcp ingest (manually ingest git commits)
  *   persyst-mcp            (if installed globally)
  */
 
@@ -19,6 +21,24 @@ const subcommand = process.argv[2];
 if (subcommand === 'setup') {
   // Delegate to the setup CLI
   await import('./bin/setup.js');
+} else if (subcommand === 'aider') {
+  // Shift 'aider' from process.argv so aider.js gets the correct arguments
+  process.argv.splice(2, 1);
+  await import('./bin/aider.js');
+} else if (subcommand === 'init') {
+  // Delegate to the rules init CLI
+  await import('./bin/init.js');
+} else if (subcommand === 'ingest') {
+  // Shift 'ingest' from process.argv so ingest.js gets the correct arguments
+  process.argv.splice(2, 1);
+  await import('./bin/ingest.js');
+} else if (subcommand === 'extract') {
+  // Shift 'extract' from process.argv so extract.js gets the correct arguments
+  process.argv.splice(2, 1);
+  await import('./bin/extract.js');
+} else if (subcommand === 'worker') {
+  // Run the background extraction worker directly
+  await import('./bin/extract-worker.js');
 } else {
   // Default: start the MCP server
   const { startServer } = await import('./src/server.js');

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "persyst-mcp",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "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-setup": "bin/setup.js",
-    "persyst-aider": "bin/aider.js"
+    "persyst-aider": "bin/aider.js",
+    "persyst-init": "bin/init.js",
+    "persyst-ingest": "bin/ingest.js",
+    "persyst-extract": "bin/extract.js",
+    "persyst-worker": "bin/extract-worker.js"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -23,7 +27,9 @@
   "scripts": {
     "start": "node index.js",
     "test": "node test/smoke.js",
-    "test:heavy": "cross-env NODE_ENV=test node --test test/test_*.js"
+    "test:heavy": "cross-env NODE_ENV=test node --test test/test_*.js",
+    "worker": "node bin/extract-worker.js",
+    "extract": "node bin/extract.js"
   },
   "keywords": [
     "mcp",