persyst-mcp 2.2.3 → 2.2.5

package/src/sdk.d.ts

@@ -0,0 +1,175 @@
+/**
+ * TypeScript type declarations for the Persyst Developer SDK.
+ * Import via: import { Persyst } from 'persyst-mcp/sdk'
+ */
+
+export interface PersystConfig {
+  /**
+   * Force a connection mode. If omitted, Persyst auto-detects.
+   * - `'gateway'` — connect to the local HTTP gateway on port 4321
+   * - `'library'` — use in-process SQLite directly (no server needed)
+   * - `null` — auto-detect: probe gateway first, fall back to library
+   */
+  mode?: 'gateway' | 'library' | null;
+  /** Gateway host (default: '127.0.0.1') */
+  host?: string;
+  /** Gateway port (default: 4321) */
+  port?: number;
+  /** Optional API key for gateway authorization */
+  apiKey?: string | null;
+}
+
+export interface TrackOptions {
+  /** Active session or thread identifier */
+  sessionId?: string;
+  /** @alias sessionId */
+  session_id?: string;
+  /**
+   * Active workflow name (used as agent_id for namespace isolation).
+   * Example: 'customer_support', 'code_review'
+   */
+  workflow?: string;
+  /**
+   * Specific event name. Used to build `content` if `content` is not provided.
+   * Example: 'payment_failed', 'build_passed'
+   */
+  event?: string;
+  /** Full text content to store as the memory. Required if `event` is not provided. */
+  content?: string;
+  /** Structured metadata to append to the generated content string. */
+  metadata?: Record<string, unknown>;
+  /** Importance score from 0.0 (low) to 1.0 (high). Default: 1.0 */
+  importance?: number;
+  /**
+   * If true (default), the memory is visible to all agents.
+   * If false, it is isolated to the `workflow` agent's namespace.
+   */
+  shared?: boolean;
+}
+
+export interface TrackResult {
+  success: boolean;
+  /** The ID of the stored (or existing) memory */
+  id: number;
+  /** The namespace the memory was written to */
+  namespace: string;
+  /** Human-readable result message */
+  message?: string;
+  /** Error message, present only on failure */
+  error?: string;
+}
+
+export interface ProvenanceRecord {
+  source_type: 'agent' | 'git' | 'api' | 'import' | 'manual';
+  source_id: string | null;
+  confidence: number;
+}
+
+export interface MemoryRecord {
+  id: number;
+  content: string;
+  importance_score: number;
+  created_at: number;
+  last_accessed: number;
+  /** Relevance score (hybrid search + reputation weight) */
+  score: number;
+  provenance?: ProvenanceRecord | null;
+}
+
+export interface ContextOptions {
+  /** Active session or thread identifier */
+  sessionId?: string;
+  /** @alias sessionId */
+  session_id?: string;
+  /** Active workflow / agent name */
+  workflow?: string;
+  /**
+   * Hint for the active task intent. Used to refine context selection.
+   * Example: 'debugging', 'ui_styling', 'database_management', 'deployment'
+   */
+  intent?: string;
+  /** Search query string — required */
+  query: string;
+  /** Hard token budget for the returned context block. Default: 2000 */
+  maxTokens?: number;
+  /** @alias maxTokens */
+  max_tokens?: number;
+}
+
+export interface ContextResult {
+  /**
+   * A formatted, ready-to-inject context string for LLM system prompts.
+   * Contains memory entries ranked by relevance within the token budget.
+   */
+  context: string;
+  /** The ranked memory records included in the context */
+  memories: MemoryRecord[];
+  /** Cryptographic Ed25519 attestation record for audit trails */
+  attestation: object | null;
+  /** Detected query intent classification */
+  intent: string;
+  /** Detected urgency level based on query language */
+  urgency: 'low' | 'medium' | 'high' | 'critical';
+  /** Generated actionable suggestions derived from retrieved memories */
+  suggested_actions: string[];
+}
+
+/**
+ * Persyst Developer SDK Client.
+ *
+ * Supports two transport modes:
+ * - **Gateway Mode**: communicates with the local HTTP gateway on port 4321.
+ *   Best for Python/other-language agents, or when the server is already running.
+ * - **Library Mode**: directly accesses the local SQLite database in-process.
+ *   Best for Node.js scripts and when no server is needed.
+ *
+ * Auto-detects the available mode on first call (150ms probe timeout).
+ *
+ * @example
+ * ```ts
+ * import { Persyst } from 'persyst-mcp/sdk';
+ *
+ * const persyst = new Persyst();
+ *
+ * // Track an architectural decision
+ * await persyst.track({
+ *   content: 'We use TypeScript for all new source files',
+ *   importance: 0.9,
+ *   workflow: 'my-agent'
+ * });
+ *
+ * // Retrieve compressed context for an LLM
+ * const { context } = await persyst.context({
+ *   query: 'coding conventions and stack choices',
+ *   intent: 'general'
+ * });
+ * console.log(context);
+ * ```
+ */
+export declare class Persyst {
+  constructor(config?: PersystConfig);
+
+  /**
+   * Track a developer event or milestone.
+   *
+   * Stores it as a persistent memory in the local SQLite database via
+   * the gateway (HTTP) or directly (library mode).
+   *
+   * If an identical memory already exists, its importance is boosted instead
+   * of creating a duplicate.
+   *
+   * @throws {Error} If neither `content` nor `event` is provided.
+   */
+  track(eventData: TrackOptions): Promise<TrackResult>;
+
+  /**
+   * Retrieve compiled, optimized context tailored by query and intent.
+   *
+   * Runs hybrid search (keyword + semantic) + knowledge graph traversal,
+   * applies temporal decay + agent reputation weighting, then compresses
+   * the result to fit within `maxTokens`.
+   *
+   * Returns a formatted context block ready to inject into an LLM system prompt.
+   */
+  context(contextQuery: ContextOptions): Promise<ContextResult>;
+}

package/src/sdk.js

@@ -0,0 +1,217 @@
+import http from 'http';
+import net from 'net';
+
+/**
+ * Persyst Developer SDK Client
+ * Supports both Gateway Mode (local HTTP server) and Library Mode (direct in-process SQLite).
+ */
+export class Persyst {
+  /**
+   * @param {Object} [config={}]
+   * @param {string} [config.mode=null] - 'gateway' | 'library' | null (auto-detect)
+   * @param {string} [config.host='127.0.0.1'] - Gateway host
+   * @param {number} [config.port=4321] - Gateway port
+   * @param {string} [config.apiKey=null] - Gateway authorization key
+   */
+  constructor(config = {}) {
+    this.mode = config.mode || null;
+    this.host = config.host || '127.0.0.1';
+    this.port = config.port || 4321;
+    this.apiKey = config.apiKey || null;
+    this._detectedMode = null;
+  }
+
+  /**
+   * Auto-detect reachable Gateway on port 4321, falling back to direct library mode.
+   * @private
+   */
+  async _resolveMode() {
+    if (this.mode) {
+      return this.mode;
+    }
+    if (this._detectedMode) {
+      return this._detectedMode;
+    }
+
+    try {
+      const isReachable = await new Promise((resolve) => {
+        const socket = new net.Socket();
+        socket.setTimeout(150); // 150ms probe timeout
+        socket.on('connect', () => {
+          socket.destroy();
+          resolve(true);
+        });
+        socket.on('error', () => {
+          socket.destroy();
+          resolve(false);
+        });
+        socket.on('timeout', () => {
+          socket.destroy();
+          resolve(false);
+        });
+        socket.connect(this.port, this.host);
+      });
+      this._detectedMode = isReachable ? 'gateway' : 'library';
+    } catch (_) {
+      this._detectedMode = 'library';
+    }
+    return this._detectedMode;
+  }
+
+  /**
+   * Track a developer event or milestone.
+   * @param {Object} eventData
+   * @param {string} [eventData.sessionId] - Active session / thread identifier
+   * @param {string} [eventData.workflow] - Active workflow name (e.g. 'customer_support')
+   * @param {string} [eventData.event] - Specific event name (e.g. 'payment_failed')
+   * @param {string} [eventData.content] - Full text detail of the event
+   * @param {Object} [eventData.metadata] - Structured metadata facts
+   * @param {number} [eventData.importance=1.0] - Importance score (0.0 - 1.0)
+   * @param {boolean} [eventData.shared=true] - Whether the memory is shared across namespaces
+   */
+  async track(eventData = {}) {
+    const mode = await this._resolveMode();
+    const sessionId = eventData.sessionId || eventData.session_id || null;
+    const workflow = eventData.workflow || null;
+    const event = eventData.event || null;
+    const metadata = eventData.metadata || null;
+    const importance = eventData.importance !== undefined ? eventData.importance : 1.0;
+    const shared = eventData.shared !== undefined ? eventData.shared : true;
+
+    let content = eventData.content || '';
+    if (!content) {
+      if (event) {
+        content = `Event: ${event}`;
+        if (workflow) content += ` in workflow: ${workflow}`;
+        if (metadata) content += `. Metadata: ${JSON.stringify(metadata)}`;
+      } else {
+        throw new Error('Either content or event must be provided to track()');
+      }
+    }
+
+    if (mode === 'gateway') {
+      return this._trackGateway({ content, importance, agent_id: workflow || 'sdk', session_id: sessionId, shared });
+    } else {
+      return this._trackLibrary({ content, importance, agent_id: workflow || 'sdk', session_id: sessionId, shared });
+    }
+  }
+
+  /**
+   * Internal direct SQLite write.
+   * @private
+   */
+  async _trackLibrary({ content, importance, agent_id, session_id, shared }) {
+    const { insertMemory, insertVector } = await import('./database.js');
+    const { generateEmbedding } = await import('./embeddings.js');
+
+    const namespace = shared ? 'shared' : agent_id;
+    const id = insertMemory(content, importance, {
+      source_type: 'api',
+      source_id: agent_id,
+      confidence: 1.0
+    }, namespace);
+
+    const embedding = await generateEmbedding(content);
+    insertVector(id, embedding);
+    return { success: true, id };
+  }
+
+  /**
+   * Internal HTTP POST write to Gateway.
+   * @private
+   */
+  _trackGateway(payload) {
+    return new Promise((resolve, reject) => {
+      const body = JSON.stringify(payload);
+      const req = http.request({
+        hostname: this.host,
+        port: this.port,
+        path: '/add',
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(body)
+        }
+      }, (res) => {
+        let responseBody = '';
+        res.on('data', chunk => { responseBody += chunk; });
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(responseBody));
+          } catch (e) {
+            reject(new Error(`Failed to parse gateway response: ${e.message}`));
+          }
+        });
+      });
+      req.on('error', reject);
+      req.write(body);
+      req.end();
+    });
+  }
+
+  /**
+   * Retrieve compiled, optimized context tailored by intent and workflow.
+   * @param {Object} contextQuery
+   * @param {string} [contextQuery.sessionId] - Active session / thread identifier
+   * @param {string} [contextQuery.workflow] - Active workflow name (e.g. 'customer_support')
+   * @param {string} [contextQuery.intent] - Active reasoning intent (e.g. 'debugging')
+   * @param {string} contextQuery.query - Prompt query string to find similar context for
+   * @param {number} [contextQuery.maxTokens=2000] - Hard budget limit of tokens
+   */
+  async context(contextQuery = {}) {
+    const mode = await this._resolveMode();
+    const sessionId = contextQuery.sessionId || contextQuery.session_id || null;
+    const workflow = contextQuery.workflow || null;
+    const intent = contextQuery.intent || null;
+    const query = contextQuery.query || '';
+    const maxTokens = contextQuery.maxTokens || contextQuery.max_tokens || 2000;
+
+    if (mode === 'gateway') {
+      return this._contextGateway({ query, max_tokens: maxTokens, agent_id: workflow, session_id: sessionId, intent });
+    } else {
+      return this._contextLibrary({ query, max_tokens: maxTokens, agent_id: workflow, session_id: sessionId, intent });
+    }
+  }
+
+  /**
+   * Internal direct SQLite read.
+   * @private
+   */
+  async _contextLibrary({ query, max_tokens, agent_id, session_id, intent }) {
+    const { getOptimizedContext } = await import('./search.js');
+    return getOptimizedContext(query, max_tokens, agent_id, session_id, agent_id || null, intent);
+  }
+
+  /**
+   * Internal HTTP POST read from Gateway.
+   * @private
+   */
+  _contextGateway(payload) {
+    return new Promise((resolve, reject) => {
+      const body = JSON.stringify(payload);
+      const req = http.request({
+        hostname: this.host,
+        port: this.port,
+        path: '/context',
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(body)
+        }
+      }, (res) => {
+        let responseBody = '';
+        res.on('data', chunk => { responseBody += chunk; });
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(responseBody));
+          } catch (e) {
+            reject(new Error(`Failed to parse gateway response: ${e.message}`));
+          }
+        });
+      });
+      req.on('error', reject);
+      req.write(body);
+      req.end();
+    });
+  }
+}

package/src/search.js

@@ -33,6 +33,12 @@ let lastDataVersion = 0;
  * @returns {Promise<Array>} Ranked search results (with .attestation property attached)
  */
 export async function searchHybrid(queryText, limit = 5, agentId = null, sessionId = null, namespace = null, skipAttestation = false) {
+  if (typeof limit !== 'number' || isNaN(limit) || limit <= 0) {
+    throw new Error('Limit must be a positive integer.');
+  }
+  const parsedLimit = Math.floor(limit);
+  const ns = namespace || 'shared';
+
   // Sync in-memory cache with external DB changes using sqlite data_version
   try {
     const currentDataVersion = db.pragma('data_version', { simple: true });
@@ -46,7 +52,7 @@ export async function searchHybrid(queryText, limit = 5, agentId = null, session
 
   // --- Check LRU cache first (Feature 1) ---
   // Include namespace in cache key to prevent cross-namespace cache hits
-  const cacheKey = LRUCache.key(`${namespace || 'all'}:${queryText}`, limit);
+  const cacheKey = LRUCache.key(`${ns}:${queryText}`, parsedLimit);
   const cached = searchCache.get(cacheKey);
   if (cached) {
     console.error(`[persyst-cache] Cache HIT for query: "${queryText.slice(0, 50)}..."`);
@@ -54,12 +60,12 @@ export async function searchHybrid(queryText, limit = 5, agentId = null, session
   }
 
   // --- Step 1: Keyword search (fast, exact matches) ---
-  const keywordHits = searchKeyword(queryText, limit * 2);
+  const keywordHits = searchKeyword(queryText, parsedLimit * 2);
   const keywordIds = new Set(keywordHits.map(r => r.id));
 
   // --- Step 2: Semantic search (meaning-based) ---
   const queryEmbedding = await generateEmbedding(queryText);
-  const vecHits = searchVector(queryEmbedding, limit * 2);
+  const vecHits = searchVector(queryEmbedding, parsedLimit * 2);
 
   const semanticResults = vecHits.map(r => ({
     id: r.rowid,
@@ -99,7 +105,7 @@ export async function searchHybrid(queryText, limit = 5, agentId = null, session
   const finalResults = combined
     .map(r => {
       // Use namespace-aware getMemoryById to filter by agent namespace
-      const memory = getMemoryById(r.id, namespace);
+      const memory = getMemoryById(r.id, ns);
       if (!memory) return null; // Memory was archived, deleted, or not in namespace
 
       // Boost memory access metrics
@@ -141,7 +147,7 @@ export async function searchHybrid(queryText, limit = 5, agentId = null, session
   finalResults.sort((a, b) => parseFloat(b.hybrid_score) - parseFloat(a.hybrid_score));
 
   // --- Step 5: Apply MMR for diverse retrieval (Feature 3) ---
-  const mmrResults = applyMMR(finalResults, limit);
+  const mmrResults = applyMMR(finalResults, parsedLimit);
 
   // Generate cryptographic attestation for audit trails (skip if called internally)
   let attestation = null;
@@ -240,7 +246,7 @@ function jaccardSimilarity(a, b) {
  * @param {string|null} agentId - Querying agent identifier
  * @param {string|null} sessionId - Current session ID
  */
-export async function getOptimizedContext(queryText, maxTokens, agentId = null, sessionId = null, namespace = null) {
+export async function getOptimizedContext(queryText, maxTokens, agentId = null, sessionId = null, namespace = null, intentParam = null) {
   // Extract entities mentioned in the query text to seed the graph search directly
   const entities = getAllEntities(100);
   const matchedEntityIds = new Set();
@@ -417,8 +423,23 @@ export async function getOptimizedContext(queryText, maxTokens, agentId = null,
     accepted.push(c);
   }
 
+  // Classify intent and urgency based on query text and parameters
+  const { intent, urgency } = classifyIntentAndUrgency(queryText, intentParam);
+  const suggested_actions = generateSuggestedActions(accepted, intent, urgency);
+
   // 6. Format LLM injection context string
   let context = '=== RETRIEVED AGENT MEMORY CONTEXT ===\n';
+  context += `[Intent: ${intent} | Urgency: ${urgency}]\n\n`;
+
+  if (suggested_actions.length > 0) {
+    context += '[Suggested Actions]\n';
+    for (const action of suggested_actions) {
+      context += `• ${action}\n`;
+    }
+    context += '\n';
+  }
+
+  context += '[Memories]\n';
   if (accepted.length === 0) {
     context += 'No relevant memories retrieved.\n';
   } else {
@@ -441,7 +462,10 @@ export async function getOptimizedContext(queryText, maxTokens, agentId = null,
   return {
     context,
     memories: accepted,
-    attestation
+    attestation,
+    intent,
+    urgency,
+    suggested_actions
   };
 }
 
@@ -625,3 +649,75 @@ export async function consolidateMemories(namespace = null) {
     details: consolidated
   };
 }
+
+/**
+ * Classify context retrieval intent and urgency level using heuristic analysis.
+ */
+function classifyIntentAndUrgency(queryText, intentParam = null) {
+  const queryLower = (queryText || '').toLowerCase();
+  
+  // 1. Determine Intent
+  let intent = intentParam || 'general';
+  if (intent === 'general' || !intent) {
+    if (/(?:db|database|sqlite|sql|table|migration|schema)/i.test(queryLower)) {
+      intent = 'database_management';
+    } else if (/(?:deploy|ci|cd|vercel|publish|release|prod|staging)/i.test(queryLower)) {
+      intent = 'deployment';
+    } else if (/(?:style|css|html|theme|design|layout|align|color|font)/i.test(queryLower)) {
+      intent = 'ui_styling';
+    } else if (/(?:test|spec|unit|mock|heavy|smoke)/i.test(queryLower)) {
+      intent = 'testing';
+    } else if (/(?:error|bug|fail|crash|break|exception|stack|trace|refused|debug)/i.test(queryLower)) {
+      intent = 'debugging';
+    }
+  }
+
+  // 2. Determine Urgency
+  let urgency = 'low';
+  if (/(?:panic|emergency|broken|critical|urgent|fatal|security|leak|bypass|vulnerability)/i.test(queryLower)) {
+    urgency = 'critical';
+  } else if (/(?:fail|error|crash|prevent|stop|warn|warning|issue|broken)/i.test(queryLower)) {
+    urgency = 'high';
+  } else if (/(?:update|change|add|tweak|check|verify)/i.test(queryLower)) {
+    urgency = 'medium';
+  }
+
+  return { intent, urgency };
+}
+
+/**
+ * Generate actionable suggested actions based on active memories and query classification.
+ */
+function generateSuggestedActions(memories, intent, urgency) {
+  const actions = [];
+
+  // General recommendation based on intent
+  if (intent === 'debugging') {
+    actions.push('Inspect the recent error logs and verify SQLite/system constraints.');
+  } else if (intent === 'ui_styling') {
+    actions.push('Verify UI layouts conform to user design preferences.');
+  } else if (intent === 'database_management') {
+    actions.push('Ensure database migrations are applied and referential integrity is checked.');
+  }
+
+  for (const m of memories) {
+    const content = m.content.toLowerCase();
+    
+    // Check for rules/decisions in memory content
+    if (content.includes('decision:') || content.includes('rule:')) {
+      actions.push(`Adhere to guideline: ${m.content.slice(0, 100)}...`);
+    } else if (content.includes('prefer')) {
+      actions.push(`Apply user preference: ${m.content.slice(0, 100)}...`);
+    } else if (content.includes('error') || content.includes('bug') || content.includes('fix')) {
+      actions.push(`Reference past fix: ${m.content.slice(0, 100)}...`);
+    }
+  }
+
+  // Safety guideline if critical
+  if (urgency === 'critical') {
+    actions.unshift('CAUTION: Address security, vulnerability, or critical stability factors immediately.');
+  }
+
+  // Deduplicate
+  return Array.from(new Set(actions));
+}