persyst-mcp 2.2.4 → 2.2.5

package/README.md

@@ -116,6 +116,13 @@ Add Persyst to your Antigravity agent configuration file at `~/.gemini/antigravi
 | `delete_memory` | Delete a memory and clean up edges | `id` (number) |
 | `get_recent_memories` | Get latest memories | `limit` (number) |
 | `get_important_memories` | Get by importance score | `limit` (number) |
+| `get_optimized_context` | Get compressed, ranked context block | `query` (string), `max_tokens` (number) |
+| `ingest_git_commits` | Import recent git commits as memories | `repo_path` (string), `count` (number) |
+| `consolidate_memories` | Merge highly similar duplicate memories | — |
+| `get_memory_history` | Retrieve all versions of a memory | `query` (string) |
+| `get_agent_stats` | Agent reputation stats | — |
+| `export_audit_log` | Export attestation audit log | `start_date`, `end_date` (ISO8601) |
+| `verify_attestation` | Verify Ed25519 signature chain | `attestation_id` (string) |
 
 ---
 
@@ -159,6 +166,38 @@ Do not run `npx` with `sudo`. If you run into permission issues, ensure your npm
 
 ---
 
+## Backup & Migration
+
+Persyst includes built-in JSONL export/import commands for portable memory backup and cross-machine migration.
+
+```bash
+# Export all memories to a file
+npx persyst-mcp export
+# → persyst-export-<timestamp>.jsonl
+
+# Export to a specific file
+npx persyst-mcp export my-backup.jsonl
+
+# Preview what would be imported (dry run)
+npx persyst-mcp import my-backup.jsonl --dry-run
+
+# Import memories (skips exact & semantic duplicates automatically)
+npx persyst-mcp import my-backup.jsonl
+```
+
+---
+
+## Roadmap & Future Directions
+
+Persyst is built for the privacy-focused solo developer. We are actively hardening the local-first experience before introducing network dependencies.
+
+* **File-Based Sync** ✅ **Done**: `persyst-export` / `persyst-import` JSONL commands for backup and migration.
+* **IDE Integrations**: First-class extensions for Cursor, VS Code, and Aider configuration helper commands.
+* **True P2P Sync (Roadmap)**: Peer-to-peer secure sync between developer devices without relying on central cloud servers.
+
+---
+
 ## License
 
 MIT License. See [LICENSE](LICENSE) for details.
+

package/bin/export.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+/**
+ * export.js — Persyst Memory JSONL Export CLI
+ *
+ * Exports all active memories to a portable JSONL file for backup or migration.
+ * Each line is a JSON object representing one memory with its full metadata.
+ *
+ * Usage:
+ *   persyst-export                          → exports to persyst-export-<timestamp>.jsonl
+ *   persyst-export memories.jsonl           → exports to memories.jsonl
+ *   persyst-export --namespace=shared       → exports only the shared namespace
+ *   persyst-export --all                    → includes archived (valid_until IS NOT NULL) memories
+ *
+ * The output format is designed to be imported back via `persyst-import`.
+ */
+
+import { createWriteStream } from 'fs';
+import db, { closeDatabase } from '../src/database.js';
+
+// ============================================================
+// ARG PARSING
+// ============================================================
+
+const args = process.argv.slice(2);
+const outputFile = args.find(a => !a.startsWith('--')) || `persyst-export-${Date.now()}.jsonl`;
+const namespace = (args.find(a => a.startsWith('--namespace=')) || '').replace('--namespace=', '') || null;
+const includeArchived = args.includes('--all');
+
+// ============================================================
+// EXPORT
+// ============================================================
+
+try {
+  const conditions = [];
+  const params = [];
+
+  if (!includeArchived) {
+    conditions.push('m.valid_until IS NULL');
+  }
+  if (namespace) {
+    conditions.push("(m.namespace = ? OR m.namespace = 'shared')");
+    params.push(namespace);
+  }
+
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+  const query = `
+    SELECT
+      m.id,
+      m.content,
+      m.importance_score,
+      m.namespace,
+      m.created_at,
+      m.last_accessed,
+      m.access_count,
+      m.parent_id,
+      m.valid_until,
+      p.source_type,
+      p.source_id,
+      p.confidence
+    FROM memories m
+    LEFT JOIN provenance p ON p.memory_id = m.id
+    ${whereClause}
+    ORDER BY m.id ASC
+  `;
+
+  const rows = params.length > 0 ? db.prepare(query).all(...params) : db.prepare(query).all();
+
+  const out = createWriteStream(outputFile, { encoding: 'utf8' });
+
+  let count = 0;
+  for (const row of rows) {
+    const record = {
+      id: row.id,
+      content: row.content,
+      importance_score: row.importance_score,
+      namespace: row.namespace || 'shared',
+      created_at: row.created_at,
+      last_accessed: row.last_accessed,
+      access_count: row.access_count,
+      parent_id: row.parent_id ?? null,
+      valid_until: row.valid_until ?? null,
+      provenance: row.source_type
+        ? {
+            source_type: row.source_type,
+            source_id: row.source_id ?? null,
+            confidence: row.confidence ?? 1.0
+          }
+        : null
+    };
+    out.write(JSON.stringify(record) + '\n');
+    count++;
+  }
+
+  await new Promise((resolve, reject) => {
+    out.end((err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+
+  console.log(`✅ Exported ${count} memories to: ${outputFile}`);
+  if (namespace) {
+    console.log(`   Namespace filter: "${namespace}" + shared`);
+  }
+  if (includeArchived) {
+    console.log('   Includes archived (superseded) memories.');
+  }
+
+} catch (err) {
+  console.error(`❌ Export failed: ${err.message}`);
+  process.exit(1);
+} finally {
+  closeDatabase();
+}

package/bin/import.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+/**
+ * import.js — Persyst Memory JSONL Import CLI
+ *
+ * Imports memories from a JSONL file created by `persyst-export`.
+ * Regenerates vector embeddings for each imported memory.
+ * Skips duplicates using both exact-content and semantic similarity checks.
+ *
+ * Usage:
+ *   persyst-import memories.jsonl
+ *   persyst-import memories.jsonl --dry-run          → preview without writing
+ *   persyst-import memories.jsonl --namespace=shared  → force all into shared namespace
+ *   persyst-import memories.jsonl --skip-embeddings   → skip re-generating embeddings (fast, no semantic search for these)
+ *
+ * Compatible with the JSONL format produced by `persyst-export`.
+ */
+
+import { createReadStream } from 'fs';
+import { createInterface } from 'readline';
+import db, {
+  insertMemory,
+  insertVector,
+  memoryExists,
+  closeDatabase
+} from '../src/database.js';
+import { generateEmbedding } from '../src/embeddings.js';
+import { searchHybrid } from '../src/search.js';
+
+// ============================================================
+// ARG PARSING
+// ============================================================
+
+const args = process.argv.slice(2);
+const inputFile = args.find(a => !a.startsWith('--'));
+const isDryRun = args.includes('--dry-run');
+const forceNamespace = (args.find(a => a.startsWith('--namespace=')) || '').replace('--namespace=', '') || null;
+const skipEmbeddings = args.includes('--skip-embeddings');
+
+const DEDUP_THRESHOLD = 0.85;
+
+if (!inputFile) {
+  console.error('❌ Usage: persyst-import <file.jsonl> [--dry-run] [--namespace=<ns>] [--skip-embeddings]');
+  process.exit(1);
+}
+
+// ============================================================
+// MAIN
+// ============================================================
+
+async function main() {
+  console.log(`📥 Persyst Import${isDryRun ? ' (DRY RUN — nothing will be written)' : ''}`);
+  console.log(`   Source: ${inputFile}`);
+  if (forceNamespace) console.log(`   Forcing namespace: "${forceNamespace}"`);
+  if (skipEmbeddings) console.log('   Skipping embedding regeneration.');
+  console.log('');
+
+  const rl = createInterface({
+    input: createReadStream(inputFile, { encoding: 'utf8' }),
+    crlfDelay: Infinity
+  });
+
+  let lineNum = 0;
+  let imported = 0;
+  let skipped = 0;
+  let errors = 0;
+
+  for await (const line of rl) {
+    lineNum++;
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    let record;
+    try {
+      record = JSON.parse(trimmed);
+    } catch (err) {
+      console.error(`  ⚠️  Line ${lineNum}: Invalid JSON — skipping`);
+      errors++;
+      continue;
+    }
+
+    const { content, importance_score = 1.0, namespace, provenance, valid_until } = record;
+
+    if (!content || typeof content !== 'string' || content.trim().length === 0) {
+      console.error(`  ⚠️  Line ${lineNum}: Empty content — skipping`);
+      errors++;
+      continue;
+    }
+
+    // Skip archived memories (unless they have a parent_id, we skip them anyway)
+    if (valid_until !== null && valid_until !== undefined) {
+      skipped++;
+      continue;
+    }
+
+    const targetNamespace = forceNamespace || namespace || 'shared';
+
+    // --- Dedup: exact content match ---
+    if (memoryExists(content, targetNamespace)) {
+      console.log(`  ⏭️  Line ${lineNum}: Already exists — skipping "${content.slice(0, 60)}..."`);
+      skipped++;
+      continue;
+    }
+
+    // --- Dedup: semantic similarity ---
+    if (!skipEmbeddings) {
+      try {
+        const similar = await searchHybrid(content, 1, null, null, targetNamespace);
+        if (similar.length > 0 && parseFloat(similar[0].similarity) >= DEDUP_THRESHOLD) {
+          console.log(`  ⏭️  Line ${lineNum}: Semantically similar to #${similar[0].id} (sim=${similar[0].similarity}) — skipping`);
+          skipped++;
+          continue;
+        }
+      } catch (_) {
+        // Non-critical: proceed with import if semantic check fails
+      }
+    }
+
+    if (isDryRun) {
+      console.log(`  ✅ Would import: "${content.slice(0, 80)}${content.length > 80 ? '...' : ''}" → ns="${targetNamespace}"`);
+      imported++;
+      continue;
+    }
+
+    // --- Write to DB ---
+    try {
+      const prov = provenance || { source_type: 'import', source_id: 'persyst-import', confidence: 1.0 };
+      const id = insertMemory(content, importance_score, prov, targetNamespace);
+
+      if (!skipEmbeddings) {
+        const embedding = await generateEmbedding(content);
+        insertVector(id, embedding);
+      }
+
+      console.log(`  ✅ Imported #${id}: "${content.slice(0, 70)}${content.length > 70 ? '...' : ''}"`);
+      imported++;
+    } catch (err) {
+      console.error(`  ❌ Line ${lineNum}: Failed to insert — ${err.message}`);
+      errors++;
+    }
+  }
+
+  console.log('');
+  console.log('═'.repeat(50));
+  if (isDryRun) {
+    console.log(`📊 Dry run complete: ${imported} would import, ${skipped} skipped, ${errors} errors`);
+  } else {
+    console.log(`📊 Import complete: ${imported} imported, ${skipped} skipped, ${errors} errors`);
+  }
+  console.log('═'.repeat(50));
+}
+
+main()
+  .catch(err => {
+    console.error(`❌ Import crashed: ${err.message}`);
+    process.exit(1);
+  })
+  .finally(() => {
+    closeDatabase();
+  });

package/hooks/persyst-hook.js

@@ -281,12 +281,11 @@ function spawnWorker() {
 /**
  * Handle SessionStart: load project-wide context and ingest git history.
  */
-async function handleSessionStart(client, input) {
+async function handleSessionStart(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', {
+  const contextResult = await callTool(null, 'get_optimized_context', {
     query: `Project ${repoName} conventions, architecture, user preferences, coding rules`,
     max_tokens: 2000,
     agent_id: 'claude-code',
@@ -295,7 +294,7 @@ async function handleSessionStart(client, input) {
 
   // 2. Ingest recent git commits (best-effort, don't fail if not a git repo)
   try {
-    await callTool(client, 'ingest_git_commits', {
+    await callTool(null, 'ingest_git_commits', {
       repo_path: cwd,
       count: 15
     });
@@ -312,11 +311,11 @@ async function handleSessionStart(client, input) {
   // 4. Get memory count for status line
   let memoryCount = 0;
   try {
-    const recentResult = await callTool(client, 'get_recent_memories', { limit: 1 });
+    const recentResult = await callTool(null, '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 });
+      const importantResult = await callTool(null, 'get_important_memories', { limit: 100 });
       memoryCount = importantResult?.count || 0;
     }
   } catch (_) {
@@ -339,7 +338,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) {
+async function handleUserPromptSubmit(input) {
   const prompt = input.prompt || '';
 
   // Skip trivial prompts (commands, confirmations, short inputs)
@@ -367,7 +366,7 @@ async function handleUserPromptSubmit(client, input) {
 
   // --- 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', {
+  const searchResult = await callTool(null, 'search_memories', {
     query: prompt.slice(0, 200), // Truncate very long prompts for search efficiency
     limit: 5,
     agent_id: 'claude-code',
@@ -448,11 +447,11 @@ async function main() {
 
     let response;
     if (eventName === 'SessionStart') {
-      response = await handleSessionStart(null, input);
+      response = await handleSessionStart(input);
     } else if (eventName === 'UserPromptSubmit') {
       // Apply hard timeout for prompt-time hook execution
       response = await Promise.race([
-        handleUserPromptSubmit(null, input),
+        handleUserPromptSubmit(input),
         new Promise((resolve) =>
           setTimeout(() => {
             process.stderr.write(`[persyst-hook] UserPromptSubmit hit ${MAX_HOOK_LATENCY_MS}ms timeout, returning partial.\n`);

package/index.js

@@ -18,7 +18,9 @@
 // If running inside Bun (like Qwen's internal runtime), spawn Node.js instead
 if (process.versions.bun && !process.env.PERSYST_RUN_BY_NODE) {
   const { spawn } = await import('child_process');
-  const child = spawn('C:\\Program Files\\nodejs\\node.exe', [
+  // Prefer NODE env var (set by nvm/fnm/volta), then fall back to 'node' on PATH
+  const nodeExec = process.env.NODE || 'node';
+  const child = spawn(nodeExec, [
     process.argv[1],
     ...process.argv.slice(2)
   ], {
@@ -80,6 +82,14 @@ if (subcommand === 'setup') {
 } else if (subcommand === 'worker') {
   // Run the background extraction worker directly
   await import('./bin/extract-worker.js');
+} else if (subcommand === 'export') {
+  // Export memories to a JSONL file
+  process.argv.splice(2, 1);
+  await import('./bin/export.js');
+} else if (subcommand === 'import') {
+  // Import memories from a JSONL file
+  process.argv.splice(2, 1);
+  await import('./bin/import.js');
 } else {
   // Default: start the MCP server
   const { startServer } = await import('./src/server.js');

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "persyst-mcp",
-  "version": "2.2.4",
+  "version": "2.2.5",
   "description": "Local-first MCP memory server with hybrid keyword + semantic search for coding agents",
   "type": "module",
   "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./sdk": {
+      "types": "./src/sdk.d.ts",
+      "default": "./src/sdk.js"
+    }
+  },
   "bin": {
     "persyst-mcp": "index.js",
     "persyst-setup": "bin/setup.js",
@@ -11,7 +18,9 @@
     "persyst-init": "bin/init.js",
     "persyst-ingest": "bin/ingest.js",
     "persyst-extract": "bin/extract.js",
-    "persyst-worker": "bin/extract-worker.js"
+    "persyst-worker": "bin/extract-worker.js",
+    "persyst-export": "bin/export.js",
+    "persyst-import": "bin/import.js"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -27,7 +36,7 @@
   "scripts": {
     "start": "node index.js",
     "test": "cross-env NODE_ENV=test node test/smoke.js",
-    "test:heavy": "cross-env NODE_ENV=test node --test --test-concurrency=1 test/test_*.js",
+    "test:heavy": "node test/run_sequentially.js",
     "worker": "node bin/extract-worker.js",
     "extract": "node bin/extract.js"
   },
@@ -60,6 +69,7 @@
     "@huggingface/transformers": "^4.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.10.0",
+    "chokidar": "^5.0.0",
     "sqlite-vec": "^0.1.9",
     "zod": "^3.23.0"
   },

package/src/database.js

@@ -34,6 +34,9 @@ const db = new Database(DB_PATH);
 db.pragma('journal_mode = WAL');   // Better performance for concurrent reads
 db.pragma('foreign_keys = ON');    // Enforce referential integrity
 db.pragma('mmap_size = 268435456'); // 256MB memory-mapped I/O for faster reads
+db.pragma('synchronous = NORMAL');  // Performance boost for WAL mode
+db.pragma('temp_store = MEMORY');   // Keep temp tables in memory
+db.pragma('cache_size = -64000');   // 64MB cache size
 
 // Load sqlite-vec BEFORE creating any vec0 tables
 sqliteVec.load(db);
@@ -330,7 +333,7 @@ const stmts = {
   decay: db.prepare(`
     UPDATE memories
     SET importance_score = ROUND(MAX(importance_score * 0.95, 0.0), 4)
-    WHERE (? - last_accessed) > 604800
+    WHERE (unixepoch() - last_accessed) > 604800
   `),
 
   // -- Search --
@@ -615,8 +618,7 @@ export function boostMemory(id) {
  * Called automatically every hour by the server.
  */
 export function applyTemporalDecay() {
-  const now = Math.floor(Date.now() / 1000);
-  const result = stmts.decay.run(now);
+  const result = stmts.decay.run();
   if (result.changes > 0) {
     console.error(`[persyst] Decay applied to ${result.changes} memories`);
   }
@@ -749,7 +751,7 @@ export function memoryExistsByHashPrefix(pattern) {
  * @returns {number}
  */
 export function getActiveMemoryCount(namespace = null) {
-  if (namespace) {
+  if (namespace && namespace !== 'all') {
     return stmts.getActiveMemoryCountNs.get(namespace).count;
   }
   return stmts.getActiveMemoryCount.get().count;

package/src/events.js

@@ -0,0 +1,19 @@
+/**
+ * events.js — Persyst In-Process Memory Event Bus
+ *
+ * A shared EventEmitter used by the HTTP gateway (SSE broadcasting),
+ * the log watcher, and the MCP tool handlers to signal memory changes
+ * in real-time without tight coupling.
+ *
+ * Events emitted:
+ *   memory_added       { id, content, namespace, source }
+ *   memory_deleted     { id }
+ *   memories_consolidated { consolidated_groups, details }
+ */
+
+import { EventEmitter } from 'events';
+
+export const memoryEventBus = new EventEmitter();
+
+// Support large swarms with many simultaneous SSE subscribers
+memoryEventBus.setMaxListeners(500);