persyst-mcp 2.0.0 → 2.1.1

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/ingest.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+/**
+ * persyst-ingest — Direct Git Commit Ingester
+ * 
+ * Usage:
+ *   npx persyst-mcp ingest [repo_path] [count]
+ * 
+ * This script runs directly without starting the MCP server, allowing
+ * git hooks or direct CLI commands to populate the memory database.
+ */
+
+import { getRecentCommits } from '../src/git.js';
+import {
+  insertMemory,
+  insertVector,
+  insertEntity,
+  insertEdge,
+  memoryExistsByHashPrefix
+} from '../src/database.js';
+import { generateEmbedding } from '../src/embeddings.js';
+import { searchCache } from '../src/cache.js';
+
+const repoPath = process.argv[2] || process.cwd();
+const count = parseInt(process.argv[3], 10) || 10;
+
+async function run() {
+  console.log(`[persyst] Ingesting git commits for: ${repoPath}`);
+  try {
+    const commits = await getRecentCommits(repoPath, count);
+    let added = 0;
+    let skipped = 0;
+
+    for (const commit of commits) {
+      const hashPrefix = commit.hash.slice(0, 7);
+      // Check if commit already exists in memories
+      if (memoryExistsByHashPrefix(`[${hashPrefix}]%`)) {
+        skipped++;
+        continue;
+      }
+
+      // Insert memory with git provenance
+      const id = insertMemory(commit.fullText, commit.importance, {
+        source_type: 'git',
+        source_id: commit.hash,
+        confidence: 0.8
+      });
+
+      // Generate embedding vector and store
+      const embedding = await generateEmbedding(commit.fullText);
+      insertVector(id, embedding);
+
+      // Link Author entity
+      const authorId = insertEntity(commit.author, 'person');
+      if (authorId) {
+        insertEdge(authorId, id, 'authored', 'entity', 'memory');
+      }
+
+      // Link Files Touched
+      for (const file of commit.files) {
+        const fileId = insertEntity(file, 'file');
+        if (fileId) {
+          insertEdge(fileId, id, 'touches', 'entity', 'memory');
+        }
+      }
+
+      added++;
+    }
+
+    if (added > 0) {
+      searchCache.invalidate();
+    }
+
+    console.log(`[persyst] Success: Ingested ${added} commits (${skipped} already existed)`);
+    process.exit(0);
+  } catch (err) {
+    console.error(`[persyst] Ingestion failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+run();

package/bin/init.js

@@ -0,0 +1,173 @@
+#!/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").
+- This ensures you are aware of existing codebase architecture, constraints, preferences, or past decisions before writing code.
+
+## 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.
+- 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

@@ -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,36 @@
  * 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)
+ *   npx persyst-mcp init   (initialize workspace rules & git hooks)
+ *   npx persyst-mcp ingest (manually ingest git commits)
  *   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 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 {
+  // 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,15 @@
 {
   "name": "persyst-mcp",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "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",
+    "persyst-init": "bin/init.js",
+    "persyst-ingest": "bin/ingest.js"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -13,6 +17,8 @@
   "files": [
     "index.js",
     "src/",
+    "bin/",
+    "hooks/",
     "README.md",
     "LICENSE"
   ],

package/src/search.js

@@ -19,6 +19,8 @@ import { generateEmbedding } from './embeddings.js';
 import { createAttestation } from './attestation.js';
 import { searchCache, LRUCache } from './cache.js';
 
+let lastDataVersion = 0;
+
 /**
  * Search memories using both keyword and semantic strategies.
  * Results are cached in the LRU cache for repeated queries.
@@ -30,6 +32,17 @@ import { searchCache, LRUCache } from './cache.js';
  * @returns {Promise<Array>} Ranked search results (with .attestation property attached)
  */
 export async function searchHybrid(queryText, limit = 5, agentId = null, sessionId = null) {
+  // Sync in-memory cache with external DB changes using sqlite data_version
+  try {
+    const currentDataVersion = db.pragma('data_version', { simple: true });
+    if (currentDataVersion !== lastDataVersion) {
+      searchCache.invalidate();
+      lastDataVersion = currentDataVersion;
+    }
+  } catch (_) {
+    // Fallback if pragma fails
+  }
+
   // --- Check LRU cache first (Feature 1) ---
   const cacheKey = LRUCache.key(queryText, limit);
   const cached = searchCache.get(cacheKey);
@@ -64,8 +77,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.1'
   });
 
   // --- Register all tools ---