@oobe-protocol-labs/sap-mcp-server 0.9.2 → 0.9.3

package/dist/memory/tool-call-store.js

@@ -0,0 +1,189 @@
+/**
+ * @module memory/tool-call-store
+ * @description Store for recording and searching tool call history.
+ *
+ * All methods are synchronous (better-sqlite3 is synchronous). FTS5 search
+ * returns relevance-ranked results using the inverted index.
+ */
+import { memoryDatabase } from './database.js';
+import { truncate } from './utils.js';
+/**
+ * @name ToolCallStore
+ * @description Records and queries tool call execution history.
+ *
+ * Every tool call (paid or free) is recorded with its input, output, outcome,
+ * cost, and latency. The FTS5 index enables full-text search across all
+ * recorded calls for pattern detection and failure analysis.
+ */
+export class ToolCallStore {
+    /**
+     * @name record
+     * @description Records a tool call execution in the memory database.
+     * @param record - Tool call data to record.
+     * @returns The auto-incremented ID of the inserted record, or -1 if degraded.
+     */
+    record(record) {
+        if (memoryDatabase.isDegraded())
+            return -1;
+        memoryDatabase.init();
+        const stmt = memoryDatabase.getStatement('insert_tool_call');
+        if (!stmt)
+            return -1;
+        const maxBytes = 8192;
+        const result = stmt.run({
+            toolName: record.toolName,
+            sessionId: record.sessionId,
+            callerProfile: record.callerProfile,
+            input: truncate(record.input, maxBytes),
+            output: truncate(record.output, maxBytes),
+            outcome: record.outcome,
+            costUsd: record.costUsd ?? null,
+            txSignature: record.txSignature ?? null,
+            latencyMs: record.latencyMs ?? null,
+        });
+        return result.lastInsertRowid;
+    }
+    /**
+     * @name search
+     * @description Full-text search across tool call history using FTS5.
+     * @param options - Search options including query, filters, and pagination.
+     * @returns Search results with relevance ranking.
+     */
+    search(options) {
+        if (memoryDatabase.isDegraded()) {
+            return { results: [], total: 0, hasMore: false };
+        }
+        memoryDatabase.init();
+        const db = memoryDatabase.getDb();
+        const limit = Math.min(options.limit ?? 20, 100);
+        const offset = options.offset ?? 0;
+        // Build FTS5 query with optional filters.
+        let whereClause = '';
+        const params = { limit, offset };
+        if (options.toolName) {
+            whereClause += ' AND t.tool_name = @toolName';
+            params['toolName'] = options.toolName;
+        }
+        if (options.outcome) {
+            whereClause += ' AND t.outcome = @outcome';
+            params['outcome'] = options.outcome;
+        }
+        // FTS5 MATCH query — use bm25 ranking for relevance.
+        const ftsQuery = this.buildFtsQuery(options.query);
+        const sql = `
+      SELECT t.id, t.tool_name, t.session_id, t.caller_profile, t.input, t.output,
+             t.outcome, t.cost_usd, t.tx_signature, t.latency_ms,
+             t.created_at, t.updated_at
+      FROM tool_calls_fts fts
+      JOIN tool_calls t ON t.id = fts.rowid
+      WHERE tool_calls_fts MATCH @ftsQuery
+      ${whereClause}
+      ORDER BY ${options.sort === 'newest' ? 't.created_at DESC' : options.sort === 'oldest' ? 't.created_at ASC' : 'bm25(tool_calls_fts)'}
+      LIMIT @limit OFFSET @offset
+    `;
+        params['ftsQuery'] = ftsQuery;
+        try {
+            const results = db.prepare(sql).all(params);
+            const countSql = `
+        SELECT COUNT(*) as total
+        FROM tool_calls_fts fts
+        JOIN tool_calls t ON t.id = fts.rowid
+        WHERE tool_calls_fts MATCH @ftsQuery ${whereClause}
+      `;
+            const countResult = db.prepare(countSql).get(params);
+            const total = countResult?.total ?? 0;
+            return {
+                results,
+                total,
+                hasMore: offset + results.length < total,
+            };
+        }
+        catch {
+            return { results: [], total: 0, hasMore: false };
+        }
+    }
+    /**
+     * @name count
+     * @description Returns the total number of tool call records.
+     */
+    count() {
+        if (memoryDatabase.isDegraded())
+            return 0;
+        memoryDatabase.init();
+        const stmt = memoryDatabase.getStatement('count_tool_calls');
+        if (!stmt)
+            return 0;
+        return stmt.get().count;
+    }
+    /**
+     * @name outcomeBreakdown
+     * @description Returns counts grouped by outcome.
+     */
+    outcomeBreakdown() {
+        if (memoryDatabase.isDegraded()) {
+            return { success: 0, error: 0, partial: 0 };
+        }
+        memoryDatabase.init();
+        const stmt = memoryDatabase.getStatement('count_tool_calls_by_outcome');
+        if (!stmt)
+            return { success: 0, error: 0, partial: 0 };
+        const rows = stmt.all();
+        const result = { success: 0, error: 0, partial: 0 };
+        for (const row of rows) {
+            result[row.outcome] = row.count;
+        }
+        return result;
+    }
+    /**
+     * @name lastToolCallAt
+     * @description Returns the timestamp of the most recent tool call.
+     */
+    lastToolCallAt() {
+        if (memoryDatabase.isDegraded())
+            return null;
+        memoryDatabase.init();
+        const stmt = memoryDatabase.getStatement('last_tool_call_at');
+        if (!stmt)
+            return null;
+        const row = stmt.get();
+        return row?.created_at ?? null;
+    }
+    /**
+     * @name archive
+     * @description Archives tool call records older than the retention period.
+     * @param retentionDays - Number of days to keep records. Default 90.
+     * @returns Number of records archived.
+     */
+    archive(retentionDays = 90) {
+        if (memoryDatabase.isDegraded())
+            return 0;
+        memoryDatabase.init();
+        const db = memoryDatabase.getDb();
+        const result = db.prepare(`DELETE FROM tool_calls WHERE created_at < datetime('now', ?)`).run(`-${retentionDays} days`);
+        return result.changes;
+    }
+    /**
+     * @name buildFtsQuery
+     * @description Converts a natural language query into a FTS5 MATCH expression.
+     * Handles multi-word queries by quoting phrases and prefixing with OR for
+     * broader recall.
+     * @internal
+     */
+    buildFtsQuery(query) {
+        // Escape FTS5 special characters and wrap in quotes for phrase matching.
+        const escaped = query.replace(/["'*:]/g, ' ').trim();
+        if (!escaped)
+            return '*';
+        // For multi-word queries, use OR to match any word (broader recall).
+        const words = escaped.split(/\s+/).filter(w => w.length > 0);
+        if (words.length === 1)
+            return `"${words[0]}"*`;
+        return words.map(w => `"${w}"*`).join(' OR ');
+    }
+}
+/**
+ * @name toolCallStore
+ * @description Singleton instance of the tool call store.
+ */
+export const toolCallStore = new ToolCallStore();
+//# sourceMappingURL=tool-call-store.js.map

package/dist/memory/tool-call-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call-store.js","sourceRoot":"","sources":["../../src/memory/tool-call-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC;;;;;;;GAOG;AACH,MAAM,OAAO,aAAa;IACxB;;;;;OAKG;IACH,MAAM,CAAC,MAA8D;QACnE,IAAI,cAAc,CAAC,UAAU,EAAE;YAAE,OAAO,CAAC,CAAC,CAAC;QAC3C,cAAc,CAAC,IAAI,EAAE,CAAC;QAEtB,MAAM,IAAI,GAAG,cAAc,CAAC,YAAY,CAAC,kBAAkB,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI;YAAE,OAAO,CAAC,CAAC,CAAC;QAErB,MAAM,QAAQ,GAAG,IAAI,CAAC;QAEtB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC;YACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC;YACvC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC;YACzC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;YAC/B,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,IAAI;YACvC,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI;SACpC,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC,eAAyB,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,OAA2B;QAChC,IAAI,cAAc,CAAC,UAAU,EAAE,EAAE,CAAC;YAChC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACnD,CAAC;QACD,cAAc,CAAC,IAAI,EAAE,CAAC;QAEtB,MAAM,EAAE,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;QAEnC,0CAA0C;QAC1C,IAAI,WAAW,GAAG,EAAE,CAAC;QACrB,MAAM,MAAM,GAA4B,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAE1D,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACrB,WAAW,IAAI,8BAA8B,CAAC;YAC9C,MAAM,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;QACxC,CAAC;QACD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,WAAW,IAAI,2BAA2B,CAAC;YAC3C,MAAM,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;QACtC,CAAC;QAED,qDAAqD;QACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAEnD,MAAM,GAAG,GAAG;;;;;;;QAOR,WAAW;iBACF,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,sBAAsB;;KAErI,CAAC;QAEF,MAAM,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC;QAE9B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAqB,CAAC;YAChE,MAAM,QAAQ,GAAG;;;;+CAIwB,WAAW;OACnD,CAAC;YACF,MAAM,WAAW,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,MAAM,CAAkC,CAAC;YACtF,MAAM,KAAK,GAAG,WAAW,EAAE,KAAK,IAAI,CAAC,CAAC;YAEtC,OAAO;gBACL,OAAO;gBACP,KAAK;gBACL,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,KAAK;aACzC,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QACnD,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,IAAI,cAAc,CAAC,UAAU,EAAE;YAAE,OAAO,CAAC,CAAC;QAC1C,cAAc,CAAC,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,cAAc,CAAC,YAAY,CAAC,kBAAkB,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI;YAAE,OAAO,CAAC,CAAC;QACpB,OAAQ,IAAI,CAAC,GAAG,EAAwB,CAAC,KAAK,CAAC;IACjD,CAAC;IAED;;;OAGG;IACH,gBAAgB;QACd,IAAI,cAAc,CAAC,UAAU,EAAE,EAAE,CAAC;YAChC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAC9C,CAAC;QACD,cAAc,CAAC,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,cAAc,CAAC,YAAY,CAAC,6BAA6B,CAAC,CAAC;QACxE,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAEvD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAwD,CAAC;QAC9E,MAAM,MAAM,GAAoC,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QACrF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC;QAClC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,cAAc;QACZ,IAAI,cAAc,CAAC,UAAU,EAAE;YAAE,OAAO,IAAI,CAAC;QAC7C,cAAc,CAAC,IAAI,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,cAAc,CAAC,YAAY,CAAC,mBAAmB,CAAC,CAAC;QAC9D,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QACvB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAwC,CAAC;QAC7D,OAAO,GAAG,EAAE,UAAU,IAAI,IAAI,CAAC;IACjC,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,aAAa,GAAG,EAAE;QACxB,IAAI,cAAc,CAAC,UAAU,EAAE;YAAE,OAAO,CAAC,CAAC;QAC1C,cAAc,CAAC,IAAI,EAAE,CAAC;QACtB,MAAM,EAAE,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CACvB,8DAA8D,CAC/D,CAAC,GAAG,CAAC,IAAI,aAAa,OAAO,CAAC,CAAC;QAChC,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC;IAED;;;;;;OAMG;IACK,aAAa,CAAC,KAAa;QACjC,yEAAyE;QACzE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACrD,IAAI,CAAC,OAAO;YAAE,OAAO,GAAG,CAAC;QAEzB,qEAAqE;QACrE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC7D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QAChD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAChD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,aAAa,EAAE,CAAC"}

package/dist/memory/types.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @module memory/types
+ * @description Type definitions for the SAP MCP local agent memory subsystem.
+ *
+ * The memory subsystem uses SQLite FTS5 to store and retrieve:
+ * - Tool call history (input, output, outcome, cost, latency)
+ * - Agent memories (LLM-compressed summaries of past interactions)
+ * - Stream buffer events (premium stream data persisted locally)
+ *
+ * All types are designed for non-custodial, local-only operation — no data
+ * leaves the user's machine. The memory DB is stored at
+ * ~/.config/sap-mcp/memory/agent-memory.db.
+ */
+/**
+ * @name ToolCallRecord
+ * @description A single tool call execution record stored in the memory DB.
+ */
+export interface ToolCallRecord {
+    /** Auto-increment primary key. */
+    id?: number;
+    /** MCP tool name (e.g. 'jupiter_getQuote', 'sap_build_sol_transfer'). */
+    toolName: string;
+    /** Session identifier from the MCP transport. */
+    sessionId: string | null;
+    /** Signer profile used for the call, if any. */
+    callerProfile: string | null;
+    /** JSON-serialized tool input. Truncated to 8KB. */
+    input: string;
+    /** JSON-serialized tool output. Truncated to 8KB. */
+    output: string;
+    /** Execution outcome classification. */
+    outcome: ToolCallOutcome;
+    /** x402 cost in USD, if the tool was paid. */
+    costUsd: number | null;
+    /** Solana transaction signature, if the tool produced one. */
+    txSignature: string | null;
+    /** Execution latency in milliseconds. */
+    latencyMs: number | null;
+    /** ISO 8601 timestamp of when the record was created. */
+    createdAt: string;
+    /** ISO 8601 timestamp of when the record was last updated. */
+    updatedAt: string;
+}
+/**
+ * @name ToolCallOutcome
+ * @description Classification of a tool call's execution result.
+ */
+export type ToolCallOutcome = 'success' | 'error' | 'partial';
+/**
+ * @name AgentMemoryRecord
+ * @description An LLM-generated summary of past agent interactions.
+ *
+ * Memories are compressed representations of tool call patterns, failures,
+ * successes, and lessons learned. They decay over time via a relevance
+ * score that decreases as memories age, ensuring the agent prioritizes
+ * recent, high-signal knowledge.
+ */
+export interface AgentMemoryRecord {
+    /** Auto-increment primary key. */
+    id?: number;
+    /** Type of memory — determines how it's used in prompt injection. */
+    memoryType: MemoryType;
+    /** Tool category this memory relates to (e.g. 'jupiter', 'adrena', 'premium'). */
+    category: string;
+    /** LLM-compressed summary text. Max 4KB. */
+    summary: string;
+    /** JSON array of tool_call IDs that were the source of this memory. */
+    sourceToolCalls: string | null;
+    /** Relevance score 0-1. Decays over time. Higher = more relevant. */
+    relevanceScore: number;
+    /** ISO 8601 timestamp of when the memory was created. */
+    createdAt: string;
+    /** ISO 8601 timestamp of when the memory expires. NULL = never expires. */
+    expiresAt: string | null;
+    /** ISO 8601 timestamp of when the memory was last accessed. */
+    lastAccessedAt: string;
+}
+/**
+ * @name MemoryType
+ * @description Classification of agent memory entries.
+ * - 'lesson': A learned pattern or rule (e.g. "Jupiter swaps fail when slippage < 50bps on low-liquidity pairs")
+ * - 'pattern': A recurring behavior (e.g. "Agent consistently buys when SOL price drops > 2%")
+ * - 'failure': A specific failure with root cause (e.g. "BlockhashNotFound after 90s — retry with fresh blockhash")
+ * - 'success': A successful outcome worth remembering (e.g. "Arb opportunity on SOL/USDC at block 123456")
+ */
+export type MemoryType = 'lesson' | 'pattern' | 'failure' | 'success';
+/**
+ * @name StreamBufferRecord
+ * @description A buffered stream event persisted locally for offline analysis.
+ */
+export interface StreamBufferRecord {
+    /** Auto-increment primary key. */
+    id?: number;
+    /** Stream type identifier (e.g. 'pyth-price', 'meme-alerts', 'volatility'). */
+    streamType: string;
+    /** Unique event ID from the provider. */
+    eventId: string;
+    /** Event type from the provider (e.g. 'price.tick', 'volatility.breakout'). */
+    eventType: string;
+    /** JSON-serialized event payload. */
+    payload: string;
+    /** Whether the event has been consumed by the agent. */
+    consumed: number;
+    /** ISO 8601 timestamp of when the event was buffered. */
+    createdAt: string;
+}
+/**
+ * @name MemorySearchResult
+ * @description A result from a full-text search across tool calls or agent memories.
+ */
+export interface MemorySearchResult<T = unknown> {
+    /** The matching records. */
+    results: T[];
+    /** Total number of matching records (before pagination). */
+    total: number;
+    /** Whether there are more results available. */
+    hasMore: boolean;
+}
+/**
+ * @name MemoryQueryOptions
+ * @description Options for searching the memory database.
+ */
+export interface MemoryQueryOptions {
+    /** FTS5 search query (e.g. 'swap failure', 'jupiter slippage'). */
+    query: string;
+    /** Filter by tool name (tool_calls only). */
+    toolName?: string;
+    /** Filter by outcome (tool_calls only). */
+    outcome?: ToolCallOutcome;
+    /** Filter by memory type (agent_memory only). */
+    memoryType?: MemoryType;
+    /** Filter by category. */
+    category?: string;
+    /** Minimum relevance score (agent_memory only). */
+    minRelevance?: number;
+    /** Maximum number of results to return. Default 20. */
+    limit?: number;
+    /** Offset for pagination. Default 0. */
+    offset?: number;
+    /** Sort order. Default 'relevance' for FTS, 'newest' for time-based. */
+    sort?: 'relevance' | 'newest' | 'oldest';
+}
+/**
+ * @name MemoryStats
+ * @description Aggregate statistics about the memory database.
+ */
+export interface MemoryStats {
+    /** Total number of tool call records. */
+    toolCallCount: number;
+    /** Total number of agent memory records. */
+    memoryCount: number;
+    /** Total number of stream buffer records (unconsumed). */
+    pendingStreamEvents: number;
+    /** Total database size in bytes. */
+    dbSizeBytes: number;
+    /** Breakdown of tool calls by outcome. */
+    outcomeBreakdown: Record<ToolCallOutcome, number>;
+    /** Breakdown of agent memories by type. */
+    memoryTypeBreakdown: Record<MemoryType, number>;
+    /** Most recent tool call timestamp. */
+    lastToolCallAt: string | null;
+    /** Most recent memory timestamp. */
+    lastMemoryAt: string | null;
+}
+/**
+ * @name MemoryPruneResult
+ * @description Result of pruning old, low-relevance memories.
+ */
+export interface MemoryPruneResult {
+    /** Number of memories pruned. */
+    pruned: number;
+    /** Number of tool calls archived (old records). */
+    archived: number;
+    /** Database size reduction in bytes. */
+    freedBytes: number;
+}
+/**
+ * @name MemoryConfig
+ * @description Configuration for the memory subsystem.
+ */
+export interface MemoryConfig {
+    /** Path to the SQLite database file. */
+    dbPath: string;
+    /** Whether to enable WAL mode (recommended for concurrent access). */
+    enableWal: boolean;
+    /** Maximum size of tool call input/output stored. Default 8192 bytes. */
+    maxPayloadBytes: number;
+    /** Relevance decay rate per day. Default 0.01 (1% per day). */
+    relevanceDecayPerDay: number;
+    /** Minimum relevance score to keep a memory. Default 0.05. */
+    minRelevanceThreshold: number;
+    /** Number of days to keep tool call records. Default 90. */
+    toolCallRetentionDays: number;
+    /** Maximum number of stream buffer events per type. Default 10000. */
+    maxStreamBufferSize: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/memory/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"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"}

package/dist/memory/types.js

@@ -0,0 +1,15 @@
+/**
+ * @module memory/types
+ * @description Type definitions for the SAP MCP local agent memory subsystem.
+ *
+ * The memory subsystem uses SQLite FTS5 to store and retrieve:
+ * - Tool call history (input, output, outcome, cost, latency)
+ * - Agent memories (LLM-compressed summaries of past interactions)
+ * - Stream buffer events (premium stream data persisted locally)
+ *
+ * All types are designed for non-custodial, local-only operation — no data
+ * leaves the user's machine. The memory DB is stored at
+ * ~/.config/sap-mcp/memory/agent-memory.db.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/memory/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/memory/utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @module memory/utils
+ * @description Utility functions for the memory subsystem.
+ */
+/**
+ * @name truncate
+ * @description Truncates a string to the specified byte length, ensuring it
+ * doesn't end in the middle of a multi-byte UTF-8 sequence.
+ * @param str - The string to truncate.
+ * @param maxBytes - Maximum byte length.
+ * @returns The truncated string.
+ */
+export declare function truncate(str: string, maxBytes: number): string;
+/**
+ * @name decayRelevance
+ * @description Computes the decayed relevance score based on days since creation.
+ * @param initialScore - Initial relevance score (0-1).
+ * @param createdAt - ISO 8601 timestamp of creation.
+ * @param decayPerDay - Decay rate per day (e.g. 0.01 = 1% per day).
+ * @returns Decayed relevance score, clamped to [0, 1].
+ */
+export declare function decayRelevance(initialScore: number, createdAt: string, decayPerDay: number): number;
+/**
+ * @name isExpired
+ * @description Checks if a memory record has expired.
+ * @param expiresAt - ISO 8601 timestamp or null (null = never expires).
+ * @returns True if the memory has expired.
+ */
+export declare function isExpired(expiresAt: string | null): boolean;
+//# sourceMappingURL=utils.d.ts.map

package/dist/memory/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/memory/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK9D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,MAAM,CAMR;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAG3D"}

package/dist/memory/utils.js

@@ -0,0 +1,47 @@
+/**
+ * @module memory/utils
+ * @description Utility functions for the memory subsystem.
+ */
+/**
+ * @name truncate
+ * @description Truncates a string to the specified byte length, ensuring it
+ * doesn't end in the middle of a multi-byte UTF-8 sequence.
+ * @param str - The string to truncate.
+ * @param maxBytes - Maximum byte length.
+ * @returns The truncated string.
+ */
+export function truncate(str, maxBytes) {
+    if (!str)
+        return '';
+    const buf = Buffer.from(str, 'utf-8');
+    if (buf.length <= maxBytes)
+        return str;
+    return buf.subarray(0, maxBytes).toString('utf-8');
+}
+/**
+ * @name decayRelevance
+ * @description Computes the decayed relevance score based on days since creation.
+ * @param initialScore - Initial relevance score (0-1).
+ * @param createdAt - ISO 8601 timestamp of creation.
+ * @param decayPerDay - Decay rate per day (e.g. 0.01 = 1% per day).
+ * @returns Decayed relevance score, clamped to [0, 1].
+ */
+export function decayRelevance(initialScore, createdAt, decayPerDay) {
+    const created = new Date(createdAt).getTime();
+    const now = Date.now();
+    const daysSince = (now - created) / (1000 * 60 * 60 * 24);
+    const decayed = initialScore * Math.pow(1 - decayPerDay, daysSince);
+    return Math.max(0, Math.min(1, decayed));
+}
+/**
+ * @name isExpired
+ * @description Checks if a memory record has expired.
+ * @param expiresAt - ISO 8601 timestamp or null (null = never expires).
+ * @returns True if the memory has expired.
+ */
+export function isExpired(expiresAt) {
+    if (!expiresAt)
+        return false;
+    return new Date(expiresAt).getTime() <= Date.now();
+}
+//# sourceMappingURL=utils.js.map

package/dist/memory/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/memory/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,QAAgB;IACpD,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACtC,IAAI,GAAG,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,GAAG,CAAC;IACvC,OAAO,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,YAAoB,EACpB,SAAiB,EACjB,WAAmB;IAEnB,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;IAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,SAAS,GAAG,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,EAAE,SAAS,CAAC,CAAC;IACpE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,SAAwB;IAChD,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7B,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;AACrD,CAAC"}

package/dist/payments/facilitator-rpc-fallback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"facilitator-rpc-fallback.d.ts","sourceRoot":"","sources":["../../src/payments/facilitator-rpc-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAGtD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAiBD;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,GAAG,oBAAoB,CAoDnH;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAMxE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAa/D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAwD3D"}
+{"version":3,"file":"facilitator-rpc-fallback.d.ts","sourceRoot":"","sources":["../../src/payments/facilitator-rpc-fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAGtD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AA0BD;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,GAAG,oBAAoB,CAoDnH;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAMxE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAa/D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAwD3D"}

package/dist/payments/facilitator-rpc-fallback.js

@@ -12,8 +12,14 @@
 import { logger, redactSensitiveString } from '../core/logger.js';
 /** Per-attempt timeout in milliseconds. If an RPC doesn't respond in this window, we move to the next. */
 const RPC_ATTEMPT_TIMEOUT_MS = 8_000;
+/** Health check interval — proactively probes endpoints every 30s. */
+const HEALTH_CHECK_INTERVAL_MS = 30_000;
 /** Round-robin counter — shared across all operations so calls distribute across endpoints. */
 let roundRobinIndex = 0;
+/** Endpoint health status — updated by periodic health checks and inline failures. */
+const endpointHealth = new Map();
+/** Health check timer handle. */
+let healthCheckTimer;
 /**
  * @name createResilientFacilitatorSigner
  * @description Wraps one or more facilitator signers with round-robin load balancing,
@@ -146,6 +152,8 @@ async function runWithRoundRobin(endpoints, operation, network, execute) {
     if (endpoints.length === 0) {
         throw new Error('No facilitator RPC endpoints configured');
     }
+    // Start health check timer if not already running
+    startHealthCheckTimer(endpoints);
     // Advance the round-robin counter — each call starts from the next endpoint.
     const startIndex = roundRobinIndex % endpoints.length;
     roundRobinIndex = (roundRobinIndex + 1) % endpoints.length;
@@ -155,9 +163,16 @@ async function runWithRoundRobin(endpoints, operation, network, execute) {
         const endpoint = endpoints[index];
         if (!endpoint)
             continue;
+        // Skip unhealthy endpoints (but still try them as last resort)
+        const health = getEndpointHealth(endpoint);
+        if (!health.healthy && attempt < endpoints.length - 1) {
+            continue;
+        }
         try {
             // Race the execution against a timeout — if the RPC is slow, we move on immediately.
             const result = await withTimeout(execute(endpoint), RPC_ATTEMPT_TIMEOUT_MS, endpoint.label, operation);
+            // Mark endpoint as healthy on success
+            markEndpointHealthy(endpoint);
             return result;
         }
         catch (error) {
@@ -165,6 +180,10 @@ async function runWithRoundRobin(endpoints, operation, network, execute) {
             const hasNext = attempt < endpoints.length - 1;
             const isTimeout = error instanceof RpcTimeoutError;
             const isTransient = isTimeout || isTransientRpcError(error);
+            // Mark endpoint as unhealthy on transient failure
+            if (isTransient) {
+                markEndpointUnhealthy(endpoint);
+            }
             if (!hasNext || !isTransient) {
                 throw error;
             }
@@ -179,6 +198,82 @@ async function runWithRoundRobin(endpoints, operation, network, execute) {
     }
     throw lastError instanceof Error ? lastError : new Error(getErrorMessage(lastError));
 }
+/**
+ * Get or initialize health status for an endpoint.
+ */
+function getEndpointHealth(endpoint) {
+    const key = endpoint.label;
+    let status = endpointHealth.get(key);
+    if (!status) {
+        status = { healthy: true, lastCheckedAt: 0, consecutiveFailures: 0 };
+        endpointHealth.set(key, status);
+    }
+    return status;
+}
+/**
+ * Mark an endpoint as healthy after a successful operation.
+ */
+function markEndpointHealthy(endpoint) {
+    const status = getEndpointHealth(endpoint);
+    status.healthy = true;
+    status.consecutiveFailures = 0;
+    status.lastCheckedAt = Date.now();
+}
+/**
+ * Mark an endpoint as unhealthy after a transient failure.
+ * After 3 consecutive failures, the endpoint is marked unhealthy until the next health check.
+ */
+function markEndpointUnhealthy(endpoint) {
+    const status = getEndpointHealth(endpoint);
+    status.consecutiveFailures += 1;
+    status.lastCheckedAt = Date.now();
+    if (status.consecutiveFailures >= 3) {
+        status.healthy = false;
+        logger.warn('Facilitator RPC endpoint marked unhealthy', {
+            endpoint: endpoint.label,
+            consecutiveFailures: status.consecutiveFailures,
+        });
+    }
+}
+/**
+ * Start periodic health check timer. Probes each endpoint every 30s with a lightweight
+ * getLatestBlockhash call. Resets unhealthy endpoints that recover.
+ */
+function startHealthCheckTimer(endpoints) {
+    if (healthCheckTimer) {
+        return; // Already running
+    }
+    healthCheckTimer = setInterval(async () => {
+        for (const endpoint of endpoints) {
+            if (!endpoint.rpcUrl)
+                continue;
+            const status = getEndpointHealth(endpoint);
+            if (status.healthy) {
+                continue; // Only probe unhealthy endpoints
+            }
+            try {
+                // Lightweight probe — just check if the RPC responds
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), 3_000);
+                const response = await fetch(endpoint.rpcUrl, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getHealth' }),
+                    signal: controller.signal,
+                });
+                clearTimeout(timeout);
+                if (response.ok) {
+                    markEndpointHealthy(endpoint);
+                    logger.info('Facilitator RPC endpoint recovered', { endpoint: endpoint.label });
+                }
+            }
+            catch {
+                // Still unhealthy — will be checked again next interval
+            }
+        }
+    }, HEALTH_CHECK_INTERVAL_MS);
+    healthCheckTimer.unref?.();
+}
 /**
  * Race a promise against a timeout. If the timeout fires, throw `RpcTimeoutError`.
  */