persyst-mcp 2.1.0 → 2.1.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/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,17 @@ 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 {
   // Default: start the MCP server
   const { startServer } = await import('./src/server.js');

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "persyst-mcp",
-  "version": "2.1.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-setup": "bin/setup.js",
-    "persyst-aider": "bin/aider.js"
+    "persyst-aider": "bin/aider.js",
+    "persyst-init": "bin/init.js",
+    "persyst-ingest": "bin/ingest.js"
   },
   "engines": {
     "node": ">=18.0.0"

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);

package/src/server.js

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