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

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"}

package/dist/memory/hermes-bridge.js

@@ -0,0 +1,155 @@
+/**
+ * @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.
+ */
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { createRequire } from 'module';
+import { logger } from '../core/logger.js';
+const require = createRequire(import.meta.url);
+/**
+ * @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 class HermesBridge {
+    hermesDir;
+    hermesDbPath;
+    available = null;
+    constructor() {
+        this.hermesDir = join(homedir(), '.hermes');
+        this.hermesDbPath = join(this.hermesDir, 'sessions.db');
+    }
+    /**
+     * @name isAvailable
+     * @description Checks whether Hermes Agent is installed on this machine.
+     * Caches the result to avoid repeated filesystem checks.
+     */
+    isAvailable() {
+        if (this.available !== null)
+            return this.available;
+        this.available = existsSync(this.hermesDir);
+        if (this.available) {
+            logger.info('Hermes Agent detected — cross-session bridge enabled', {
+                hermesDir: this.hermesDir,
+            });
+        }
+        return this.available;
+    }
+    /**
+     * @name getHermesDir
+     * @description Returns the Hermes installation directory.
+     */
+    getHermesDir() {
+        return this.hermesDir;
+    }
+    /**
+     * @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, limit = 5) {
+        if (!this.isAvailable())
+            return [];
+        if (!existsSync(this.hermesDbPath))
+            return [];
+        try {
+            // Use dynamic import to avoid loading better-sqlite3 if Hermes is not present.
+            const Database = require('better-sqlite3');
+            const db = new Database(this.hermesDbPath, { readonly: true });
+            try {
+                // Try FTS5 search first (if Hermes has it).
+                const ftsResults = db.prepare(`SELECT s.id, s.title, substr(m.content, 1, 200) as snippet, s.created_at
+           FROM messages m
+           JOIN sessions s ON s.id = m.session_id
+           WHERE m.content MATCH ?
+           ORDER BY s.created_at DESC
+           LIMIT ?`).all(query, limit);
+                return ftsResults.map(r => ({
+                    sessionId: r.id,
+                    title: r.title ?? 'Untitled',
+                    snippet: r.snippet,
+                    timestamp: r.created_at,
+                }));
+            }
+            catch {
+                // FTS not available — try LIKE search.
+                const likeResults = db.prepare(`SELECT s.id, s.title, substr(m.content, 1, 200) as snippet, s.created_at
+           FROM messages m
+           JOIN sessions s ON s.id = m.session_id
+           WHERE m.content LIKE ?
+           ORDER BY s.created_at DESC
+           LIMIT ?`).all(`%${query}%`, limit);
+                return likeResults.map(r => ({
+                    sessionId: r.id,
+                    title: r.title ?? 'Untitled',
+                    snippet: r.snippet,
+                    timestamp: r.created_at,
+                }));
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (error) {
+            logger.debug('Hermes bridge query failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
+    /**
+     * @name getRecentSessions
+     * @description Returns recent Hermes sessions for context injection.
+     * @param limit - Max sessions. Default 3.
+     */
+    getRecentSessions(limit = 3) {
+        if (!this.isAvailable())
+            return [];
+        if (!existsSync(this.hermesDbPath))
+            return [];
+        try {
+            const Database = require('better-sqlite3');
+            const db = new Database(this.hermesDbPath, { readonly: true });
+            try {
+                const results = db.prepare(`SELECT id, title, created_at FROM sessions
+           ORDER BY created_at DESC LIMIT ?`).all(limit);
+                return results.map(r => ({
+                    sessionId: r.id,
+                    title: r.title ?? 'Untitled',
+                    timestamp: r.created_at,
+                }));
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch {
+            return [];
+        }
+    }
+}
+/**
+ * @name hermesBridge
+ * @description Singleton instance of the Hermes bridge.
+ */
+export const hermesBridge = new HermesBridge();
+//# sourceMappingURL=hermes-bridge.js.map

package/dist/memory/hermes-bridge.js.map

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

package/dist/memory/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module memory
+ * @description SAP MCP local agent memory subsystem — SQLite FTS5 backed.
+ *
+ * Exports all stores and types for use by the MCP tool registration layer.
+ *
+ * Architecture:
+ * - database.ts: Thread-safe singleton SQLite connection with WAL mode + FTS5.
+ * - tool-call-store.ts: Records and searches tool call history.
+ * - memory-store.ts: Manages LLM-generated agent memories with relevance decay.
+ * - stream-buffer-store.ts: Buffers premium stream events for offline consumption.
+ * - types.ts: Type definitions.
+ * - utils.ts: Utility functions (truncate, decay, expiry).
+ */
+export { MemoryDatabase, memoryDatabase, DEFAULT_CONFIG } from './database.js';
+export { ToolCallStore, toolCallStore } from './tool-call-store.js';
+export { MemoryStore, memoryStore } from './memory-store.js';
+export { StreamBufferStore, streamBufferStore } from './stream-buffer-store.js';
+export { AsyncMemoryProcessor, asyncMemoryProcessor } from './async-processor.js';
+export { recordToolCall } from './auto-record.js';
+export { HermesBridge, hermesBridge } from './hermes-bridge.js';
+export type { ToolCallRecord, ToolCallOutcome, AgentMemoryRecord, MemoryType, StreamBufferRecord, MemorySearchResult, MemoryQueryOptions, MemoryStats, MemoryPruneResult, MemoryConfig, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/memory/index.js

@@ -0,0 +1,22 @@
+/**
+ * @module memory
+ * @description SAP MCP local agent memory subsystem — SQLite FTS5 backed.
+ *
+ * Exports all stores and types for use by the MCP tool registration layer.
+ *
+ * Architecture:
+ * - database.ts: Thread-safe singleton SQLite connection with WAL mode + FTS5.
+ * - tool-call-store.ts: Records and searches tool call history.
+ * - memory-store.ts: Manages LLM-generated agent memories with relevance decay.
+ * - stream-buffer-store.ts: Buffers premium stream events for offline consumption.
+ * - types.ts: Type definitions.
+ * - utils.ts: Utility functions (truncate, decay, expiry).
+ */
+export { MemoryDatabase, memoryDatabase, DEFAULT_CONFIG } from './database.js';
+export { ToolCallStore, toolCallStore } from './tool-call-store.js';
+export { MemoryStore, memoryStore } from './memory-store.js';
+export { StreamBufferStore, streamBufferStore } from './stream-buffer-store.js';
+export { AsyncMemoryProcessor, asyncMemoryProcessor } from './async-processor.js';
+export { recordToolCall } from './auto-record.js';
+export { HermesBridge, hermesBridge } from './hermes-bridge.js';
+//# sourceMappingURL=index.js.map

package/dist/memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAChF,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}