@oobe-protocol-labs/sap-mcp-server 0.9.22 → 0.9.35

package/dist/memory/auto-record.js

@@ -0,0 +1,133 @@
+/**
+ * @module memory/auto-record
+ * @description Automatic tool call recording hook.
+ *
+ * Wraps the MCP tool handler to automatically record every tool call in the
+ * local memory database — no agent action required. The hook measures
+ * latency, captures the outcome, and stores truncated input/output.
+ *
+ * The hook is designed to be non-blocking: if the memory DB is degraded or
+ * the recording fails, the tool call proceeds normally. Recording errors
+ * are logged but never propagated to the caller.
+ */
+import { toolCallStore } from './tool-call-store.js';
+import { memoryDatabase } from './database.js';
+import { logger } from '../core/logger.js';
+/**
+ * @name recordToolCall
+ * @description Records a tool call execution in the memory database.
+ *
+ * This function is called after every tool handler executes. It captures:
+ * - toolName: the MCP tool name
+ * - input: JSON-serialized input (truncated to 8KB)
+ * - output: JSON-serialized output (truncated to 8KB)
+ * - outcome: 'success' | 'error' | 'partial'
+ * - latencyMs: wall-clock time from start to finish
+ * - costUsd: estimated from the pricing tier (if available)
+ * - txSignature: extracted from the output if present
+ *
+ * The function never throws — recording failures are logged and swallowed.
+ *
+ * @param toolName - The MCP tool name.
+ * @param input - The raw input object passed to the tool.
+ * @param output - The tool result text.
+ * @param isError - Whether the tool returned an error.
+ * @param latencyMs - Execution latency in milliseconds.
+ * @param sessionId - Optional session identifier.
+ * @param callerProfile - Optional signer profile.
+ */
+export function recordToolCall(toolName, input, output, isError, latencyMs, sessionId, callerProfile) {
+    // Skip recording for memory tools themselves — avoid infinite recursion.
+    if (toolName.startsWith('sap_memory_') || toolName.startsWith('sap_audit_') || toolName.startsWith('sap_strategy_') || toolName.startsWith('sap_stream_')) {
+        return;
+    }
+    // Skip if the memory database is degraded.
+    if (memoryDatabase.isDegraded())
+        return;
+    try {
+        // Serialize input/output with truncation.
+        const inputJson = safeStringify(input, 8192);
+        const outputJson = safeStringify(output, 8192);
+        // Determine outcome.
+        const outcome = isError ? 'error' : determineOutcome(output);
+        // Extract transaction signature from output if present.
+        const txSignature = extractTxSignature(output);
+        // Record in the database.
+        toolCallStore.record({
+            toolName,
+            sessionId: sessionId ?? null,
+            callerProfile: callerProfile ?? null,
+            input: inputJson,
+            output: outputJson,
+            outcome,
+            costUsd: null, // Cost is tracked by the x402 gate, not here.
+            txSignature,
+            latencyMs,
+        });
+    }
+    catch (error) {
+        // Never propagate recording errors — the tool call already succeeded.
+        logger.debug('Auto-record failed', {
+            toolName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * @name determineOutcome
+ * @description Classifies the tool call outcome from the output text.
+ * Checks for partial success indicators (e.g. "partial", "some failed", "retry").
+ * @internal
+ */
+function determineOutcome(output) {
+    const lower = output.toLowerCase();
+    if (lower.includes('"partial"') || lower.includes('"some failed"') || lower.includes('"retry-safe": false')) {
+        return 'partial';
+    }
+    return 'success';
+}
+/**
+ * @name extractTxSignature
+ * @description Extracts a Solana transaction signature from the tool output.
+ * Looks for common patterns like "signature": "..." or "txSignature": "...".
+ * @internal
+ */
+function extractTxSignature(output) {
+    // Try JSON parsing first.
+    try {
+        const parsed = JSON.parse(output);
+        if (typeof parsed['signature'] === 'string')
+            return parsed['signature'];
+        if (typeof parsed['txSignature'] === 'string')
+            return parsed['txSignature'];
+        if (typeof parsed['transactionSignature'] === 'string')
+            return parsed['transactionSignature'];
+    }
+    catch {
+        // Not JSON — try regex.
+    }
+    // Regex fallback for base58 signatures (64-88 chars).
+    const match = output.match(/\b[1-9A-HJ-NP-Za-km-z]{64,88}\b/);
+    return match ? match[0] : null;
+}
+/**
+ * @name safeStringify
+ * @description Safely serializes a value to JSON with truncation.
+ * Handles circular references and large objects.
+ * @internal
+ */
+function safeStringify(value, maxBytes) {
+    try {
+        const json = JSON.stringify(value);
+        if (!json)
+            return '';
+        const buf = Buffer.from(json, 'utf-8');
+        if (buf.length <= maxBytes)
+            return json;
+        return buf.subarray(0, maxBytes).toString('utf-8') + '...[truncated]';
+    }
+    catch {
+        return String(value).slice(0, maxBytes);
+    }
+}
+//# sourceMappingURL=auto-record.js.map

package/dist/memory/auto-record.js.map

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

package/dist/memory/database.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @module memory/database
+ * @description Thread-safe SQLite database manager for the SAP MCP agent memory subsystem.
+ *
+ * Uses better-sqlite3 (synchronous, native, FTS5-enabled) with WAL mode for
+ * concurrent read access. The database is a singleton — one connection per process.
+ *
+ * Design principles:
+ * - Synchronous I/O: better-sqlite3 is synchronous, no async overhead, no callback hell.
+ * - WAL mode: readers don't block writers, crash-safe via WAL journal.
+ * - Prepared statements: cached for performance, reused across calls.
+ * - FTS5: inverted full-text index for relevance-ranked retrieval.
+ * - Schema versioning: idempotent migrations on init.
+ * - Graceful degradation: if the DB can't be opened, tools return empty results.
+ */
+import type { Database as DatabaseType, Statement } from 'better-sqlite3';
+import type { MemoryConfig } from './types.js';
+/**
+ * @name DEFAULT_CONFIG
+ * @description Default memory configuration. The DB is stored in
+ * ~/.config/mcp-sap/memory/ which is the standard SAP MCP config directory.
+ */
+export declare const DEFAULT_CONFIG: MemoryConfig;
+/**
+ * @name MemoryDatabase
+ * @description Thread-safe singleton managing the SQLite connection for agent memory.
+ *
+ * The class lazily initializes the database on first access and caches prepared
+ * statements for performance. All methods are synchronous (better-sqlite3 is
+ * synchronous by design). The database runs in WAL mode for concurrent reads.
+ *
+ * If the database cannot be opened (e.g. disk full, permissions), the instance
+ * enters a degraded mode where all queries return empty results instead of
+ * crashing the MCP server.
+ */
+export declare class MemoryDatabase {
+    private db;
+    private readonly config;
+    private degraded;
+    private initialized;
+    private statements;
+    constructor(config?: Partial<MemoryConfig>);
+    /**
+     * @name init
+     * @description Initializes the database connection, creates the schema, and
+     * enables WAL mode. Called lazily on first query.
+     */
+    init(): void;
+    /**
+     * @name getDb
+     * @description Returns the underlying Database instance. Throws if degraded.
+     * @internal
+     */
+    getDb(): DatabaseType;
+    /**
+     * @name isDegraded
+     * @description Returns true if the database is in degraded mode (init failed).
+     */
+    isDegraded(): boolean;
+    /**
+     * @name getStatement
+     * @description Returns a cached prepared statement by key.
+     * @internal
+     */
+    getStatement(key: string): Statement | undefined;
+    /**
+     * @name close
+     * @description Closes the database connection gracefully.
+     */
+    close(): void;
+    /**
+     * @name getDbSize
+     * @description Returns the database file size in bytes.
+     */
+    getDbSize(): number;
+    /**
+     * @name runMigrations
+     * @description Runs idempotent schema migrations. Each migration checks if
+     * the current schema version is below the target and applies changes.
+     * @internal
+     */
+    private runMigrations;
+    /**
+     * @name migrateToV1
+     * @description Creates the initial schema: tool_calls, agent_memory,
+     * stream_buffers, and their FTS5 indexes.
+     * @internal
+     */
+    private migrateToV1;
+    /**
+     * @name prepareStatements
+     * @description Pre-compiles and caches frequently used SQL statements.
+     * @internal
+     */
+    private prepareStatements;
+}
+/**
+ * @name memoryDatabase
+ * @description Singleton instance of the memory database.
+ * Lazily initialized on first access. Shared across all memory tools.
+ */
+export declare const memoryDatabase: MemoryDatabase;
+//# sourceMappingURL=database.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/memory/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAK1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAS/C;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,YAQ5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,EAAE,CAA6B;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAqC;gBAE3C,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM;IAI9C;;;;OAIG;IACI,IAAI,IAAI,IAAI;IA0CnB;;;;OAIG;IACI,KAAK,IAAI,YAAY;IAO5B;;;OAGG;IACI,UAAU,IAAI,OAAO;IAI5B;;;;OAIG;IACI,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIvD;;;OAGG;IACI,KAAK,IAAI,IAAI;IAapB;;;OAGG;IACI,SAAS,IAAI,MAAM;IAU1B;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IA4BrB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAkHnB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;CAyD1B;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,gBAAuB,CAAC"}

package/dist/memory/database.js

@@ -0,0 +1,337 @@
+/**
+ * @module memory/database
+ * @description Thread-safe SQLite database manager for the SAP MCP agent memory subsystem.
+ *
+ * Uses better-sqlite3 (synchronous, native, FTS5-enabled) with WAL mode for
+ * concurrent read access. The database is a singleton — one connection per process.
+ *
+ * Design principles:
+ * - Synchronous I/O: better-sqlite3 is synchronous, no async overhead, no callback hell.
+ * - WAL mode: readers don't block writers, crash-safe via WAL journal.
+ * - Prepared statements: cached for performance, reused across calls.
+ * - FTS5: inverted full-text index for relevance-ranked retrieval.
+ * - Schema versioning: idempotent migrations on init.
+ * - Graceful degradation: if the DB can't be opened, tools return empty results.
+ */
+import Database from 'better-sqlite3';
+import { mkdirSync, statSync } from 'fs';
+import { dirname, join } from 'path';
+import { logger } from '../core/logger.js';
+import { getMemoryDir } from '../config/paths.js';
+/**
+ * @name SCHEMA_VERSION
+ * @description Current schema version. Increment when the schema changes.
+ * The database tracks this in the `_meta` table and runs migrations as needed.
+ */
+const SCHEMA_VERSION = 1;
+/**
+ * @name DEFAULT_CONFIG
+ * @description Default memory configuration. The DB is stored in
+ * ~/.config/mcp-sap/memory/ which is the standard SAP MCP config directory.
+ */
+export const DEFAULT_CONFIG = {
+    dbPath: join(getMemoryDir(), 'agent-memory.db'),
+    enableWal: true,
+    maxPayloadBytes: 8192,
+    relevanceDecayPerDay: 0.01,
+    minRelevanceThreshold: 0.05,
+    toolCallRetentionDays: 90,
+    maxStreamBufferSize: 10_000,
+};
+/**
+ * @name MemoryDatabase
+ * @description Thread-safe singleton managing the SQLite connection for agent memory.
+ *
+ * The class lazily initializes the database on first access and caches prepared
+ * statements for performance. All methods are synchronous (better-sqlite3 is
+ * synchronous by design). The database runs in WAL mode for concurrent reads.
+ *
+ * If the database cannot be opened (e.g. disk full, permissions), the instance
+ * enters a degraded mode where all queries return empty results instead of
+ * crashing the MCP server.
+ */
+export class MemoryDatabase {
+    db = null;
+    config;
+    degraded = false;
+    initialized = false;
+    statements = new Map();
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * @name init
+     * @description Initializes the database connection, creates the schema, and
+     * enables WAL mode. Called lazily on first query.
+     */
+    init() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+        try {
+            // Ensure the directory exists.
+            const dir = dirname(this.config.dbPath);
+            mkdirSync(dir, { recursive: true });
+            // Open the database with better-sqlite3.
+            this.db = new Database(this.config.dbPath);
+            // Enable WAL mode for concurrent read access and crash safety.
+            if (this.config.enableWal) {
+                this.db.pragma('journal_mode = WAL');
+                this.db.pragma('synchronous = NORMAL');
+                this.db.pragma('wal_autocheckpoint = 1000');
+            }
+            // Set busy timeout to 5 seconds for concurrent access.
+            this.db.pragma('busy_timeout = 5000');
+            // Run schema migrations.
+            this.runMigrations();
+            // Prepare cached statements.
+            this.prepareStatements();
+            logger.info('Memory database initialized', {
+                path: this.config.dbPath,
+                wal: this.config.enableWal,
+                schemaVersion: SCHEMA_VERSION,
+            });
+        }
+        catch (error) {
+            logger.error('Memory database initialization failed — entering degraded mode', {
+                error: error instanceof Error ? error.message : String(error),
+                path: this.config.dbPath,
+            });
+            this.degraded = true;
+        }
+    }
+    /**
+     * @name getDb
+     * @description Returns the underlying Database instance. Throws if degraded.
+     * @internal
+     */
+    getDb() {
+        if (this.degraded || !this.db) {
+            throw new Error('Memory database is in degraded mode — queries return empty results.');
+        }
+        return this.db;
+    }
+    /**
+     * @name isDegraded
+     * @description Returns true if the database is in degraded mode (init failed).
+     */
+    isDegraded() {
+        return this.degraded;
+    }
+    /**
+     * @name getStatement
+     * @description Returns a cached prepared statement by key.
+     * @internal
+     */
+    getStatement(key) {
+        return this.statements.get(key);
+    }
+    /**
+     * @name close
+     * @description Closes the database connection gracefully.
+     */
+    close() {
+        if (this.db) {
+            try {
+                this.db.close();
+            }
+            catch {
+                // Best-effort close.
+            }
+            this.db = null;
+        }
+        this.statements.clear();
+        this.initialized = false;
+    }
+    /**
+     * @name getDbSize
+     * @description Returns the database file size in bytes.
+     */
+    getDbSize() {
+        try {
+            return statSync(this.config.dbPath).size;
+        }
+        catch {
+            return 0;
+        }
+    }
+    // ── Schema Migrations ──────────────────────────────────────────────────────
+    /**
+     * @name runMigrations
+     * @description Runs idempotent schema migrations. Each migration checks if
+     * the current schema version is below the target and applies changes.
+     * @internal
+     */
+    runMigrations() {
+        if (!this.db)
+            return;
+        // Create _meta table if it doesn't exist.
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS _meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+    `);
+        // Get current schema version.
+        const versionRow = this.db.prepare('SELECT value FROM _meta WHERE key = ?').get('schema_version');
+        const currentVersion = versionRow ? parseInt(versionRow.value, 10) : 0;
+        if (currentVersion < 1) {
+            this.migrateToV1();
+        }
+        // Update schema version.
+        this.db.prepare('INSERT OR REPLACE INTO _meta (key, value) VALUES (?, ?)').run('schema_version', SCHEMA_VERSION.toString());
+    }
+    /**
+     * @name migrateToV1
+     * @description Creates the initial schema: tool_calls, agent_memory,
+     * stream_buffers, and their FTS5 indexes.
+     * @internal
+     */
+    migrateToV1() {
+        if (!this.db)
+            return;
+        this.db.exec(`
+      -- Tool call history
+      CREATE TABLE IF NOT EXISTS tool_calls (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        tool_name TEXT NOT NULL,
+        session_id TEXT,
+        caller_profile TEXT,
+        input TEXT,
+        output TEXT,
+        outcome TEXT NOT NULL DEFAULT 'success',
+        cost_usd REAL DEFAULT 0,
+        tx_signature TEXT,
+        latency_ms INTEGER,
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_tool_calls_tool ON tool_calls(tool_name);
+      CREATE INDEX IF NOT EXISTS idx_tool_calls_session ON tool_calls(session_id);
+      CREATE INDEX IF NOT EXISTS idx_tool_calls_outcome ON tool_calls(outcome);
+      CREATE INDEX IF NOT EXISTS idx_tool_calls_created ON tool_calls(created_at);
+
+      -- FTS5 inverted index for tool call search
+      CREATE VIRTUAL TABLE IF NOT EXISTS tool_calls_fts USING fts5(
+        tool_name,
+        input,
+        output,
+        content='tool_calls',
+        content_rowid='id'
+      );
+
+      -- Triggers to keep FTS index in sync with tool_calls
+      CREATE TRIGGER IF NOT EXISTS tool_calls_ai AFTER INSERT ON tool_calls BEGIN
+        INSERT INTO tool_calls_fts(rowid, tool_name, input, output)
+        VALUES (new.id, new.tool_name, new.input, new.output);
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS tool_calls_ad AFTER DELETE ON tool_calls BEGIN
+        INSERT INTO tool_calls_fts(tool_calls_fts, rowid, tool_name, input, output)
+        VALUES ('delete', old.id, old.tool_name, old.input, old.output);
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS tool_calls_au AFTER UPDATE ON tool_calls BEGIN
+        INSERT INTO tool_calls_fts(tool_calls_fts, rowid, tool_name, input, output)
+        VALUES ('delete', old.id, old.tool_name, old.input, old.output);
+        INSERT INTO tool_calls_fts(rowid, tool_name, input, output)
+        VALUES (new.id, new.tool_name, new.input, new.output);
+      END;
+
+      -- Agent memory — LLM-generated summaries
+      CREATE TABLE IF NOT EXISTS agent_memory (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        memory_type TEXT NOT NULL,
+        category TEXT NOT NULL,
+        summary TEXT NOT NULL,
+        source_tool_calls TEXT,
+        relevance_score REAL DEFAULT 0.5,
+        created_at TEXT DEFAULT (datetime('now')),
+        expires_at TEXT,
+        last_accessed_at TEXT DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_agent_memory_category ON agent_memory(category);
+      CREATE INDEX IF NOT EXISTS idx_agent_memory_relevance ON agent_memory(relevance_score);
+      CREATE INDEX IF NOT EXISTS idx_agent_memory_type ON agent_memory(memory_type);
+
+      -- FTS5 inverted index for agent memory search
+      CREATE VIRTUAL TABLE IF NOT EXISTS agent_memory_fts USING fts5(
+        memory_type,
+        category,
+        summary,
+        content='agent_memory',
+        content_rowid='id'
+      );
+
+      -- Triggers to keep FTS index in sync with agent_memory
+      CREATE TRIGGER IF NOT EXISTS agent_memory_ai AFTER INSERT ON agent_memory BEGIN
+        INSERT INTO agent_memory_fts(rowid, memory_type, category, summary)
+        VALUES (new.id, new.memory_type, new.category, new.summary);
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS agent_memory_ad AFTER DELETE ON agent_memory BEGIN
+        INSERT INTO agent_memory_fts(agent_memory_fts, rowid, memory_type, category, summary)
+        VALUES ('delete', old.id, old.memory_type, old.category, old.summary);
+      END;
+
+      CREATE TRIGGER IF NOT EXISTS agent_memory_au AFTER UPDATE ON agent_memory BEGIN
+        INSERT INTO agent_memory_fts(agent_memory_fts, rowid, memory_type, category, summary)
+        VALUES ('delete', old.id, old.memory_type, old.category, old.summary);
+        INSERT INTO agent_memory_fts(rowid, memory_type, category, summary)
+        VALUES (new.id, new.memory_type, new.category, new.summary);
+      END;
+
+      -- Stream buffer events
+      CREATE TABLE IF NOT EXISTS stream_buffers (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        stream_type TEXT NOT NULL,
+        event_id TEXT NOT NULL,
+        event_type TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        consumed INTEGER DEFAULT 0,
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_stream_buffers_type ON stream_buffers(stream_type);
+      CREATE INDEX IF NOT EXISTS idx_stream_buffers_consumed ON stream_buffers(consumed);
+      CREATE INDEX IF NOT EXISTS idx_stream_buffers_created ON stream_buffers(created_at);
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_stream_buffers_event ON stream_buffers(stream_type, event_id);
+    `);
+    }
+    /**
+     * @name prepareStatements
+     * @description Pre-compiles and caches frequently used SQL statements.
+     * @internal
+     */
+    prepareStatements() {
+        if (!this.db)
+            return;
+        // Tool calls
+        this.statements.set('insert_tool_call', this.db.prepare(`INSERT INTO tool_calls (tool_name, session_id, caller_profile, input, output, outcome, cost_usd, tx_signature, latency_ms)
+       VALUES (@toolName, @sessionId, @callerProfile, @input, @output, @outcome, @costUsd, @txSignature, @latencyMs)`));
+        this.statements.set('count_tool_calls', this.db.prepare('SELECT COUNT(*) as count FROM tool_calls'));
+        this.statements.set('count_tool_calls_by_outcome', this.db.prepare('SELECT outcome, COUNT(*) as count FROM tool_calls GROUP BY outcome'));
+        this.statements.set('last_tool_call_at', this.db.prepare('SELECT created_at FROM tool_calls ORDER BY id DESC LIMIT 1'));
+        // Agent memory
+        this.statements.set('insert_memory', this.db.prepare(`INSERT INTO agent_memory (memory_type, category, summary, source_tool_calls, relevance_score, expires_at)
+       VALUES (@memoryType, @category, @summary, @sourceToolCalls, @relevanceScore, @expiresAt)`));
+        this.statements.set('count_memory', this.db.prepare('SELECT COUNT(*) as count FROM agent_memory'));
+        this.statements.set('count_memory_by_type', this.db.prepare('SELECT memory_type, COUNT(*) as count FROM agent_memory GROUP BY memory_type'));
+        this.statements.set('last_memory_at', this.db.prepare('SELECT created_at FROM agent_memory ORDER BY id DESC LIMIT 1'));
+        this.statements.set('update_memory_access', this.db.prepare('UPDATE agent_memory SET last_accessed_at = datetime(\'now\') WHERE id = ?'));
+        // Stream buffers
+        this.statements.set('count_pending_streams', this.db.prepare('SELECT COUNT(*) as count FROM stream_buffers WHERE consumed = 0'));
+        this.statements.set('insert_stream_event', this.db.prepare(`INSERT OR IGNORE INTO stream_buffers (stream_type, event_id, event_type, payload, consumed)
+       VALUES (@streamType, @eventId, @eventType, @payload, 0)`));
+        this.statements.set('consume_stream_events', this.db.prepare('UPDATE stream_buffers SET consumed = 1 WHERE stream_type = ? AND id <= ?'));
+    }
+}
+/**
+ * @name memoryDatabase
+ * @description Singleton instance of the memory database.
+ * Lazily initialized on first access. Shared across all memory tools.
+ */
+export const memoryDatabase = new MemoryDatabase();
+//# sourceMappingURL=database.js.map

package/dist/memory/database.js.map

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

package/dist/memory/hermes-bridge.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @module memory/hermes-bridge
+ * @description Cross-session integration with Hermes Agent session database.
+ *
+ * If the user has Hermes Agent installed (detected via ~/.hermes/ directory),
+ * the memory subsystem can query Hermes session history for cross-session
+ * context. This enables the agent to recall relevant conversations from
+ * previous Hermes sessions while keeping the data local.
+ *
+ * If Hermes is not installed, all bridge functions return empty results —
+ * the memory subsystem operates standalone.
+ */
+/**
+ * @name HermesBridge
+ * @description Bridges the SAP MCP memory subsystem with Hermes Agent session data.
+ *
+ * Detection: checks for ~/.hermes/ directory. If present, the bridge can query
+ * the Hermes SQLite session database for relevant past conversations.
+ */
+export declare class HermesBridge {
+    private readonly hermesDir;
+    private readonly hermesDbPath;
+    private available;
+    constructor();
+    /**
+     * @name isAvailable
+     * @description Checks whether Hermes Agent is installed on this machine.
+     * Caches the result to avoid repeated filesystem checks.
+     */
+    isAvailable(): boolean;
+    /**
+     * @name getHermesDir
+     * @description Returns the Hermes installation directory.
+     */
+    getHermesDir(): string;
+    /**
+     * @name searchSessions
+     * @description Searches Hermes session history for relevant past conversations.
+     *
+     * This is a lightweight bridge — it reads the Hermes session database using
+     * the same better-sqlite3 driver (opening a read-only connection). The query
+     * uses FTS5 if the Hermes DB has it, otherwise falls back to LIKE search.
+     *
+     * @param query - Search query (natural language).
+     * @param limit - Max results. Default 5.
+     * @returns Array of session snippets with timestamps.
+     */
+    searchSessions(query: string, limit?: number): Array<{
+        sessionId: string;
+        title: string;
+        snippet: string;
+        timestamp: string;
+    }>;
+    /**
+     * @name getRecentSessions
+     * @description Returns recent Hermes sessions for context injection.
+     * @param limit - Max sessions. Default 3.
+     */
+    getRecentSessions(limit?: number): Array<{
+        sessionId: string;
+        title: string;
+        timestamp: string;
+    }>;
+}
+/**
+ * @name hermesBridge
+ * @description Singleton instance of the Hermes bridge.
+ */
+export declare const hermesBridge: HermesBridge;
+//# sourceMappingURL=hermes-bridge.d.ts.map

package/dist/memory/hermes-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hermes-bridge.d.ts","sourceRoot":"","sources":["../../src/memory/hermes-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,SAAS,CAAwB;;IAOzC;;;;OAIG;IACH,WAAW,IAAI,OAAO;IAWtB;;;OAGG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAsDzH;;;;OAIG;IACH,iBAAiB,CAAC,KAAK,SAAI,GAAG,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CA0B7F;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,cAAqB,CAAC"}