@adaptivemcp/memory 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./store.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./store.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}

package/dist/store.d.ts

@@ -0,0 +1,39 @@
+import { type DatabaseSyncOptions } from "node:sqlite";
+import type { Annotation, Insight, Recommendation, RecommendationType, ToolExecutionEvent, ToolRecord } from "@adaptivemcp/spec";
+export interface MemoryStoreOptions {
+    /** Path to the SQLite database file. Use ":memory:" for an in-memory store. */
+    path?: string;
+    dbOptions?: DatabaseSyncOptions;
+}
+/**
+ * SQLite-backed single source of truth for Adaptive MCP.
+ *
+ * All tool metadata — annotations, learned insights, recommendations, and raw
+ * stats — is persisted here. The YAML tools-metadata view is a *derived*
+ * projection of this store, never the source of truth.
+ */
+export declare class MemoryStore {
+    private db;
+    constructor(options?: MemoryStoreOptions);
+    close(): void;
+    /** Ensure a tool record exists, seeding it with an empty annotation. */
+    ensureTool(toolName: string, serverName?: string): ToolRecord;
+    getTool(toolName: string): ToolRecord | undefined;
+    allTools(): ToolRecord[];
+    /** Persist a human-written annotation (the static metadata layer). */
+    setAnnotation(annotation: Annotation): ToolRecord;
+    /** Record a learned insight derived from observed behavior. */
+    addInsight(insight: Insight): ToolRecord;
+    /** Store a suggested adaptation. */
+    addRecommendation(rec: Recommendation): ToolRecord;
+    /**
+     * Remove all recommendations of a given type for a tool. Used by the routing,
+     * orchestration, and approval packages so each adaptation pass recomputes its
+     * own recommendations instead of appending duplicates on every observation.
+     */
+    clearRecommendations(toolName: string, type: RecommendationType): ToolRecord;
+    /** Fold a tool execution event into the persisted stats. */
+    recordExecution(event: ToolExecutionEvent): ToolRecord;
+    private write;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EACV,UAAU,EACV,OAAO,EACP,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,UAAU,EAEX,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,mBAAmB,CAAC;CACjC;AAwBD;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,EAAE,CAAe;gBAEb,OAAO,GAAE,kBAAuB;IAK5C,KAAK,IAAI,IAAI;IAIb,wEAAwE;IACxE,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU;IA+B7D,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAOjD,QAAQ,IAAI,UAAU,EAAE;IAOxB,sEAAsE;IACtE,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU;IAWjD,+DAA+D;IAC/D,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU;IAYxC,oCAAoC;IACpC,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,UAAU;IAWlD;;;;OAIG;IACH,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,UAAU;IAW5E,4DAA4D;IAC5D,eAAe,CAAC,KAAK,EAAE,kBAAkB,GAAG,UAAU;IAatD,OAAO,CAAC,KAAK;CAiBd"}

package/dist/store.js

@@ -0,0 +1,171 @@
+import { DatabaseSync } from "node:sqlite";
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS tools (
+  tool_name TEXT PRIMARY KEY,
+  server_name TEXT,
+  annotation TEXT NOT NULL,
+  insights TEXT NOT NULL DEFAULT '[]',
+  recommendations TEXT NOT NULL DEFAULT '[]',
+  stats TEXT NOT NULL DEFAULT '{}',
+  updated_at TEXT NOT NULL
+);
+`;
+/**
+ * SQLite-backed single source of truth for Adaptive MCP.
+ *
+ * All tool metadata — annotations, learned insights, recommendations, and raw
+ * stats — is persisted here. The YAML tools-metadata view is a *derived*
+ * projection of this store, never the source of truth.
+ */
+export class MemoryStore {
+    db;
+    constructor(options = {}) {
+        this.db = new DatabaseSync(options.path ?? ":memory:", options.dbOptions ?? {});
+        this.db.exec(SCHEMA);
+    }
+    close() {
+        this.db.close();
+    }
+    /** Ensure a tool record exists, seeding it with an empty annotation. */
+    ensureTool(toolName, serverName) {
+        const existing = this.getTool(toolName);
+        if (existing)
+            return existing;
+        const now = new Date().toISOString();
+        const record = {
+            toolName,
+            serverName,
+            annotation: { toolName },
+            insights: [],
+            recommendations: [],
+            stats: emptyStats(),
+            updatedAt: now,
+        };
+        this.db
+            .prepare(`INSERT INTO tools (tool_name, server_name, annotation, insights, recommendations, stats, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`)
+            .run(toolName, serverName ?? null, JSON.stringify(record.annotation), JSON.stringify(record.insights), JSON.stringify(record.recommendations), JSON.stringify(record.stats), now);
+        return record;
+    }
+    getTool(toolName) {
+        const row = this.db
+            .prepare(`SELECT * FROM tools WHERE tool_name = ?`)
+            .get(toolName);
+        return row ? deserialize(row) : undefined;
+    }
+    allTools() {
+        const rows = this.db
+            .prepare(`SELECT * FROM tools ORDER BY tool_name`)
+            .all();
+        return rows.map(deserialize);
+    }
+    /** Persist a human-written annotation (the static metadata layer). */
+    setAnnotation(annotation) {
+        const record = this.ensureTool(annotation.toolName);
+        const updated = {
+            ...record,
+            annotation: { ...record.annotation, ...annotation },
+            updatedAt: new Date().toISOString(),
+        };
+        this.write(updated);
+        return updated;
+    }
+    /** Record a learned insight derived from observed behavior. */
+    addInsight(insight) {
+        const record = this.ensureTool(insight.toolName);
+        const insights = [...record.insights.filter((i) => i.key !== insight.key), insight];
+        const updated = {
+            ...record,
+            insights,
+            updatedAt: new Date().toISOString(),
+        };
+        this.write(updated);
+        return updated;
+    }
+    /** Store a suggested adaptation. */
+    addRecommendation(rec) {
+        const record = this.ensureTool(rec.toolName);
+        const updated = {
+            ...record,
+            recommendations: [...record.recommendations, rec],
+            updatedAt: new Date().toISOString(),
+        };
+        this.write(updated);
+        return updated;
+    }
+    /**
+     * Remove all recommendations of a given type for a tool. Used by the routing,
+     * orchestration, and approval packages so each adaptation pass recomputes its
+     * own recommendations instead of appending duplicates on every observation.
+     */
+    clearRecommendations(toolName, type) {
+        const record = this.ensureTool(toolName);
+        const updated = {
+            ...record,
+            recommendations: record.recommendations.filter((r) => r.type !== type),
+            updatedAt: new Date().toISOString(),
+        };
+        this.write(updated);
+        return updated;
+    }
+    /** Fold a tool execution event into the persisted stats. */
+    recordExecution(event) {
+        const record = this.ensureTool(event.toolName, event.serverName);
+        const stats = foldEvent(record.stats, event);
+        const updated = {
+            ...record,
+            serverName: record.serverName ?? event.serverName,
+            stats,
+            updatedAt: new Date().toISOString(),
+        };
+        this.write(updated);
+        return updated;
+    }
+    write(record) {
+        this.db
+            .prepare(`UPDATE tools
+         SET server_name = ?, annotation = ?, insights = ?, recommendations = ?, stats = ?, updated_at = ?
+         WHERE tool_name = ?`)
+            .run(record.serverName ?? null, JSON.stringify(record.annotation), JSON.stringify(record.insights), JSON.stringify(record.recommendations), JSON.stringify(record.stats), record.updatedAt, record.toolName);
+    }
+}
+function emptyStats() {
+    return {
+        invocations: 0,
+        failures: 0,
+        failureRate: 0,
+        avgDurationMs: null,
+        totalCost: 0,
+        lastObservedAt: null,
+    };
+}
+function foldEvent(stats, event) {
+    const invocations = stats.invocations + 1;
+    const failures = stats.failures + (event.status === "failed" ? 1 : 0);
+    const durations = event.durationMs != null ? [event.durationMs] : [];
+    const prevAvg = stats.avgDurationMs ?? 0;
+    const avgDurationMs = durations.length > 0
+        ? (prevAvg * (invocations - 1) + durations[0]) / invocations
+        : stats.avgDurationMs;
+    const totalCost = stats.totalCost + (event.cost?.amount ?? 0);
+    return {
+        invocations,
+        failures,
+        failureRate: failures / invocations,
+        avgDurationMs,
+        totalCost,
+        lastObservedAt: event.timestamp,
+    };
+}
+function deserialize(row) {
+    return {
+        toolName: row.tool_name,
+        serverName: row.server_name ?? undefined,
+        annotation: JSON.parse(row.annotation),
+        insights: JSON.parse(row.insights),
+        recommendations: JSON.parse(row.recommendations),
+        stats: JSON.parse(row.stats),
+        updatedAt: row.updated_at,
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@adaptivemcp/memory",
+  "version": "0.2.0",
+  "description": "Persistent operational knowledge for Adaptive MCP, backed by SQLite (node:sqlite).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run --config ../../vitest.config.ts"
+  },
+  "dependencies": {
+    "@adaptivemcp/spec": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}