@ulrichc1/sparn 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
 /**
  * Core memory entry types for Sparn's context optimization engine.
  * Maps to neuroscience-inspired memory model with decay and state transitions.
@@ -241,6 +243,8 @@ interface RealtimeConfig {
     incremental: boolean;
     /** Sliding window size for context entries (default: 500) */
     windowSize: number;
+    /** Consolidation interval in hours, or null for disabled (default: null) */
+    consolidationInterval: number | null;
 }
 /**
  * Complete Sparn configuration.
@@ -906,6 +910,35 @@ interface SessionWatcher {
  */
 declare function createSessionWatcher(config: SessionWatcherConfig): SessionWatcher;
 
+/**
+ * Sparn MCP Server - Model Context Protocol server implementation
+ *
+ * Exposes Sparn's neuroscience-inspired context optimization as MCP tools,
+ * enabling integration with Claude Desktop, VS Code, and other MCP clients.
+ *
+ * Tools:
+ * - sparn_optimize: Optimize context with configurable options
+ * - sparn_stats: Get optimization statistics
+ * - sparn_consolidate: Run memory consolidation (sleep replay)
+ */
+
+/**
+ * Options for creating the Sparn MCP server.
+ */
+interface SparnMcpServerOptions {
+    /** KV memory store instance */
+    memory: KVMemory;
+    /** Sparn configuration (defaults to DEFAULT_CONFIG) */
+    config?: SparnConfig;
+}
+/**
+ * Create and configure the Sparn MCP server with all tools registered.
+ *
+ * @param options - Server options including memory store and config
+ * @returns Configured McpServer instance ready to connect to a transport
+ */
+declare function createSparnMcpServer(options: SparnMcpServerOptions): McpServer;
+
 /**
  * Context Parser - Shared utilities for parsing agent contexts into memory entries
  *
@@ -1003,4 +1036,4 @@ declare function createLogger(verbose?: boolean): Logger;
  */
 declare function estimateTokens(text: string): number;
 
-export { type AgentAdapter, type AgentType, type BTSPEmbedder, type BlockType, type BudgetPruner, type BudgetPrunerConfig, type ConfidenceState, type ConfidenceStates, type ConfidenceStatesConfig, type ConsolidateResult, type ContextPipeline, type ContextPipelineConfig, type ContextPipelineStats, DEFAULT_CONFIG, type DaemonCommand, type DaemonStartResult, type DaemonStatusResult, type DaemonStopResult, type DecayConfig, type DuplicateGroup, type EngramScorer, type EngramScorerConfig, type FilePosition, type FileTracker, type IncrementalOptimizer, type IncrementalOptimizerConfig, type IncrementalOptimizerState, type KVMemory, type LogLevel, type Logger, type MemoryEntry, type MemoryQueryFilters, type OptimizationResult, type OptimizeOptions, type PruneResult, type PruningConfig, type RealtimeConfig, type SessionStats, type SessionWatcher, type SessionWatcherConfig, type SleepCompressor, type SparnConfig, type SparsePruner, type SparsePrunerConfig, type StateDistribution, type StatesConfig, type UIConfig, createBTSPEmbedder, createBudgetPruner, createBudgetPrunerFromConfig, createClaudeCodeAdapter, createConfidenceStates, createContextPipeline, createDaemonCommand, createEngramScorer, createEntry, createFileTracker, createGenericAdapter, createIncrementalOptimizer, createKVMemory, createLogger, createSessionWatcher, createSleepCompressor, createSparsePruner, estimateTokens, hashContent, parseClaudeCodeContext, parseGenericContext };
+export { type AgentAdapter, type AgentType, type BTSPEmbedder, type BlockType, type BudgetPruner, type BudgetPrunerConfig, type ConfidenceState, type ConfidenceStates, type ConfidenceStatesConfig, type ConsolidateResult, type ContextPipeline, type ContextPipelineConfig, type ContextPipelineStats, DEFAULT_CONFIG, type DaemonCommand, type DaemonStartResult, type DaemonStatusResult, type DaemonStopResult, type DecayConfig, type DuplicateGroup, type EngramScorer, type EngramScorerConfig, type FilePosition, type FileTracker, type IncrementalOptimizer, type IncrementalOptimizerConfig, type IncrementalOptimizerState, type KVMemory, type LogLevel, type Logger, type MemoryEntry, type MemoryQueryFilters, type OptimizationResult, type OptimizeOptions, type PruneResult, type PruningConfig, type RealtimeConfig, type SessionStats, type SessionWatcher, type SessionWatcherConfig, type SleepCompressor, type SparnConfig, type SparnMcpServerOptions, type SparsePruner, type SparsePrunerConfig, type StateDistribution, type StatesConfig, type UIConfig, createBTSPEmbedder, createBudgetPruner, createBudgetPrunerFromConfig, createClaudeCodeAdapter, createConfidenceStates, createContextPipeline, createDaemonCommand, createEngramScorer, createEntry, createFileTracker, createGenericAdapter, createIncrementalOptimizer, createKVMemory, createLogger, createSessionWatcher, createSleepCompressor, createSparnMcpServer, createSparsePruner, estimateTokens, hashContent, parseClaudeCodeContext, parseGenericContext };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
 /**
  * Core memory entry types for Sparn's context optimization engine.
  * Maps to neuroscience-inspired memory model with decay and state transitions.
@@ -241,6 +243,8 @@ interface RealtimeConfig {
     incremental: boolean;
     /** Sliding window size for context entries (default: 500) */
     windowSize: number;
+    /** Consolidation interval in hours, or null for disabled (default: null) */
+    consolidationInterval: number | null;
 }
 /**
  * Complete Sparn configuration.
@@ -906,6 +910,35 @@ interface SessionWatcher {
  */
 declare function createSessionWatcher(config: SessionWatcherConfig): SessionWatcher;
 
+/**
+ * Sparn MCP Server - Model Context Protocol server implementation
+ *
+ * Exposes Sparn's neuroscience-inspired context optimization as MCP tools,
+ * enabling integration with Claude Desktop, VS Code, and other MCP clients.
+ *
+ * Tools:
+ * - sparn_optimize: Optimize context with configurable options
+ * - sparn_stats: Get optimization statistics
+ * - sparn_consolidate: Run memory consolidation (sleep replay)
+ */
+
+/**
+ * Options for creating the Sparn MCP server.
+ */
+interface SparnMcpServerOptions {
+    /** KV memory store instance */
+    memory: KVMemory;
+    /** Sparn configuration (defaults to DEFAULT_CONFIG) */
+    config?: SparnConfig;
+}
+/**
+ * Create and configure the Sparn MCP server with all tools registered.
+ *
+ * @param options - Server options including memory store and config
+ * @returns Configured McpServer instance ready to connect to a transport
+ */
+declare function createSparnMcpServer(options: SparnMcpServerOptions): McpServer;
+
 /**
  * Context Parser - Shared utilities for parsing agent contexts into memory entries
  *
@@ -1003,4 +1036,4 @@ declare function createLogger(verbose?: boolean): Logger;
  */
 declare function estimateTokens(text: string): number;
 
-export { type AgentAdapter, type AgentType, type BTSPEmbedder, type BlockType, type BudgetPruner, type BudgetPrunerConfig, type ConfidenceState, type ConfidenceStates, type ConfidenceStatesConfig, type ConsolidateResult, type ContextPipeline, type ContextPipelineConfig, type ContextPipelineStats, DEFAULT_CONFIG, type DaemonCommand, type DaemonStartResult, type DaemonStatusResult, type DaemonStopResult, type DecayConfig, type DuplicateGroup, type EngramScorer, type EngramScorerConfig, type FilePosition, type FileTracker, type IncrementalOptimizer, type IncrementalOptimizerConfig, type IncrementalOptimizerState, type KVMemory, type LogLevel, type Logger, type MemoryEntry, type MemoryQueryFilters, type OptimizationResult, type OptimizeOptions, type PruneResult, type PruningConfig, type RealtimeConfig, type SessionStats, type SessionWatcher, type SessionWatcherConfig, type SleepCompressor, type SparnConfig, type SparsePruner, type SparsePrunerConfig, type StateDistribution, type StatesConfig, type UIConfig, createBTSPEmbedder, createBudgetPruner, createBudgetPrunerFromConfig, createClaudeCodeAdapter, createConfidenceStates, createContextPipeline, createDaemonCommand, createEngramScorer, createEntry, createFileTracker, createGenericAdapter, createIncrementalOptimizer, createKVMemory, createLogger, createSessionWatcher, createSleepCompressor, createSparsePruner, estimateTokens, hashContent, parseClaudeCodeContext, parseGenericContext };
+export { type AgentAdapter, type AgentType, type BTSPEmbedder, type BlockType, type BudgetPruner, type BudgetPrunerConfig, type ConfidenceState, type ConfidenceStates, type ConfidenceStatesConfig, type ConsolidateResult, type ContextPipeline, type ContextPipelineConfig, type ContextPipelineStats, DEFAULT_CONFIG, type DaemonCommand, type DaemonStartResult, type DaemonStatusResult, type DaemonStopResult, type DecayConfig, type DuplicateGroup, type EngramScorer, type EngramScorerConfig, type FilePosition, type FileTracker, type IncrementalOptimizer, type IncrementalOptimizerConfig, type IncrementalOptimizerState, type KVMemory, type LogLevel, type Logger, type MemoryEntry, type MemoryQueryFilters, type OptimizationResult, type OptimizeOptions, type PruneResult, type PruningConfig, type RealtimeConfig, type SessionStats, type SessionWatcher, type SessionWatcherConfig, type SleepCompressor, type SparnConfig, type SparnMcpServerOptions, type SparsePruner, type SparsePrunerConfig, type StateDistribution, type StatesConfig, type UIConfig, createBTSPEmbedder, createBudgetPruner, createBudgetPrunerFromConfig, createClaudeCodeAdapter, createConfidenceStates, createContextPipeline, createDaemonCommand, createEngramScorer, createEntry, createFileTracker, createGenericAdapter, createIncrementalOptimizer, createKVMemory, createLogger, createSessionWatcher, createSleepCompressor, createSparnMcpServer, createSparsePruner, estimateTokens, hashContent, parseClaudeCodeContext, parseGenericContext };

package/dist/index.js

@@ -1,10 +1,3 @@
-// node_modules/tsup/assets/esm_shims.js
-import path from "path";
-import { fileURLToPath } from "url";
-var getFilename = () => fileURLToPath(import.meta.url);
-var getDirname = () => path.dirname(getFilename());
-var __dirname = /* @__PURE__ */ getDirname();
-
 // src/core/btsp-embedder.ts
 import { randomUUID } from "crypto";
 
@@ -1316,6 +1309,7 @@ function createSleepCompressor() {
 import { fork } from "child_process";
 import { existsSync as existsSync2, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
 import { dirname, join } from "path";
+import { fileURLToPath } from "url";
 function createDaemonCommand() {
   function isDaemonRunning(pidFile) {
     if (!existsSync2(pidFile)) {
@@ -1362,7 +1356,9 @@ function createDaemonCommand() {
       };
     }
     try {
-      const daemonPath = join(__dirname, "index.js");
+      const __filename2 = fileURLToPath(import.meta.url);
+      const __dirname2 = dirname(__filename2);
+      const daemonPath = join(__dirname2, "index.js");
       const child = fork(daemonPath, [], {
         detached: true,
         stdio: "ignore",
@@ -1711,6 +1707,10 @@ function createSessionWatcher(config) {
   };
 }
 
+// src/mcp/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
 // src/types/config.ts
 var DEFAULT_CONFIG = {
   pruning: {
@@ -1740,10 +1740,217 @@ var DEFAULT_CONFIG = {
     logFile: ".sparn/daemon.log",
     debounceMs: 5e3,
     incremental: true,
-    windowSize: 500
+    windowSize: 500,
+    consolidationInterval: null
   }
 };
 
+// src/mcp/server.ts
+function createSparnMcpServer(options) {
+  const { memory, config = DEFAULT_CONFIG } = options;
+  const server = new McpServer({
+    name: "sparn",
+    version: "1.1.1"
+  });
+  registerOptimizeTool(server, memory, config);
+  registerStatsTool(server, memory);
+  registerConsolidateTool(server, memory);
+  return server;
+}
+function registerOptimizeTool(server, memory, config) {
+  server.registerTool(
+    "sparn_optimize",
+    {
+      title: "Sparn Optimize",
+      description: "Optimize context using neuroscience-inspired pruning. Applies BTSP detection, engram scoring, confidence states, and sparse pruning to reduce token usage while preserving important information.",
+      inputSchema: {
+        context: z.string().describe("The context text to optimize"),
+        dryRun: z.boolean().optional().default(false).describe("If true, do not persist changes to the memory store"),
+        verbose: z.boolean().optional().default(false).describe("If true, include per-entry details in the response"),
+        threshold: z.number().min(0).max(100).optional().describe("Custom pruning threshold (1-100, overrides config)")
+      }
+    },
+    async ({ context, dryRun, verbose, threshold }) => {
+      try {
+        const effectiveConfig = threshold ? { ...config, pruning: { ...config.pruning, threshold } } : config;
+        const adapter = createGenericAdapter(memory, effectiveConfig);
+        const result = await adapter.optimize(context, {
+          dryRun,
+          verbose,
+          threshold
+        });
+        const response = {
+          optimizedContext: result.optimizedContext,
+          tokensBefore: result.tokensBefore,
+          tokensAfter: result.tokensAfter,
+          reduction: `${(result.reduction * 100).toFixed(1)}%`,
+          entriesProcessed: result.entriesProcessed,
+          entriesKept: result.entriesKept,
+          durationMs: result.durationMs,
+          stateDistribution: result.stateDistribution,
+          ...verbose && result.details ? { details: result.details } : {}
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(response, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: message })
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+function registerStatsTool(server, memory) {
+  server.registerTool(
+    "sparn_stats",
+    {
+      title: "Sparn Stats",
+      description: "Get optimization statistics including total commands run, tokens saved, and average reduction percentage.",
+      inputSchema: {
+        reset: z.boolean().optional().default(false).describe("If true, reset all optimization statistics")
+      }
+    },
+    async ({ reset }) => {
+      try {
+        if (reset) {
+          await memory.clearOptimizationStats();
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    message: "Optimization statistics have been reset.",
+                    totalCommands: 0,
+                    totalTokensSaved: 0,
+                    averageReduction: "0.0%"
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        const stats = await memory.getOptimizationStats();
+        const totalCommands = stats.length;
+        const totalTokensSaved = stats.reduce(
+          (sum, s) => sum + (s.tokens_before - s.tokens_after),
+          0
+        );
+        const averageReduction = totalCommands > 0 ? stats.reduce((sum, s) => {
+          const reduction = s.tokens_before > 0 ? (s.tokens_before - s.tokens_after) / s.tokens_before : 0;
+          return sum + reduction;
+        }, 0) / totalCommands : 0;
+        const recentOptimizations = stats.slice(0, 10).map((s) => ({
+          timestamp: new Date(s.timestamp).toISOString(),
+          tokensBefore: s.tokens_before,
+          tokensAfter: s.tokens_after,
+          entriesPruned: s.entries_pruned,
+          durationMs: s.duration_ms,
+          reduction: `${((s.tokens_before - s.tokens_after) / Math.max(s.tokens_before, 1) * 100).toFixed(1)}%`
+        }));
+        const response = {
+          totalCommands,
+          totalTokensSaved,
+          averageReduction: `${(averageReduction * 100).toFixed(1)}%`,
+          recentOptimizations
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(response, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: message })
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+function registerConsolidateTool(server, memory) {
+  server.registerTool(
+    "sparn_consolidate",
+    {
+      title: "Sparn Consolidate",
+      description: "Run memory consolidation (sleep replay). Removes decayed entries and merges duplicates to reclaim space. Inspired by the neuroscience principle of sleep-based memory consolidation."
+    },
+    async () => {
+      try {
+        const allIds = await memory.list();
+        const allEntries = await Promise.all(
+          allIds.map(async (id) => {
+            const entry = await memory.get(id);
+            return entry;
+          })
+        );
+        const entries = allEntries.filter((e) => e !== null);
+        const compressor = createSleepCompressor();
+        const result = compressor.consolidate(entries);
+        for (const removed of result.removed) {
+          await memory.delete(removed.id);
+        }
+        for (const kept of result.kept) {
+          await memory.put(kept);
+        }
+        await memory.compact();
+        const response = {
+          entriesBefore: result.entriesBefore,
+          entriesAfter: result.entriesAfter,
+          decayedRemoved: result.decayedRemoved,
+          duplicatesRemoved: result.duplicatesRemoved,
+          compressionRatio: `${(result.compressionRatio * 100).toFixed(1)}%`,
+          durationMs: result.durationMs,
+          vacuumCompleted: true
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(response, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: message })
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
 // src/utils/logger.ts
 function createLogger(verbose = false) {
   return {
@@ -1781,6 +1988,7 @@ export {
   createLogger,
   createSessionWatcher,
   createSleepCompressor,
+  createSparnMcpServer,
   createSparsePruner,
   estimateTokens,
   hashContent,