@drqedwards/pmll 2.0.4

package/dist/peek.d.ts

@@ -0,0 +1,67 @@
+/**
+ * peek.ts — Main guard function for MCP context deduplication.
+ *
+ * `peekContext()` is the primary primitive that agents call **before**
+ * any expensive MCP tool invocation (e.g. a Playwright navigation or a
+ * remote API call).  It checks two layers:
+ *
+ * 1. The in-process KV store (`PMMemoryStore`) — analogous to reading the
+ *    PMLL memory silo (PMLL.c::init_silo / update_silo) for a cached result.
+ * 2. The Q-promise registry (`QPromiseRegistry`) — analogous to checking
+ *    whether a `QMemNode` chain is still in-flight (Q_promise_lib pending).
+ *
+ * If both layers miss, the caller is expected to proceed with the real tool
+ * call and then invoke `store.set(key, value)` to populate the cache for
+ * future agents.
+ */
+import { PMMemoryStore } from "./kv-store.js";
+import { QPromiseRegistry } from "./q-promise-bridge.js";
+/** Return shape for a KV cache hit. */
+export interface PeekHitResult {
+    hit: true;
+    value: string;
+    index: number;
+}
+/** Return shape for a Q-promise pending hit. */
+export interface PeekPendingResult {
+    hit: true;
+    status: "pending";
+    promise_id: string;
+}
+/** Return shape for a full miss. */
+export interface PeekMissResult {
+    hit: false;
+}
+export type PeekContextResult = PeekHitResult | PeekPendingResult | PeekMissResult;
+/**
+ * Check whether `key` is already resolved for `sessionId`.
+ *
+ * The function implements a two-stage guard:
+ *
+ * Stage 1 — KV store hit (PMLL silo cache):
+ *     If the key exists and is resolved, return the cached value
+ *     immediately.  This eliminates the need to re-invoke the
+ *     corresponding MCP tool entirely.
+ *
+ * Stage 2 — Q-promise pending check:
+ *     If the key is registered as an in-flight promise, return a
+ *     `pending` indicator so the caller can await resolution rather
+ *     than launching a duplicate tool call.
+ *
+ * Stage 3 — Full miss:
+ *     Neither layer has seen this key.  The caller should proceed with
+ *     the real MCP tool call and then call `store.set(key, value)`
+ *     to populate the cache.
+ *
+ * @param key              The context key to look up (e.g. a URL, task ID).
+ * @param sessionId        Identifies the current agent session (for logging).
+ * @param store            The session's `PMMemoryStore` instance.
+ * @param promiseRegistry  Shared `QPromiseRegistry` instance.
+ *
+ * @returns One of:
+ *   - `{ hit: true, value: string, index: number }`          — KV hit
+ *   - `{ hit: true, status: "pending", promise_id: string }` — in-flight
+ *   - `{ hit: false }`                                        — full miss
+ */
+export declare function peekContext(key: string, sessionId: string, store: PMMemoryStore, promiseRegistry: QPromiseRegistry): PeekContextResult;
+//# sourceMappingURL=peek.d.ts.map

package/dist/peek.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peek.d.ts","sourceRoot":"","sources":["../src/peek.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,IAAI,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,MAAM,EAAE,SAAS,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,KAAK,CAAC;CACZ;AAED,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,iBAAiB,GAAG,cAAc,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,aAAa,EACpB,eAAe,EAAE,gBAAgB,GAChC,iBAAiB,CAenB"}

package/dist/peek.js

@@ -0,0 +1,61 @@
+/**
+ * peek.ts — Main guard function for MCP context deduplication.
+ *
+ * `peekContext()` is the primary primitive that agents call **before**
+ * any expensive MCP tool invocation (e.g. a Playwright navigation or a
+ * remote API call).  It checks two layers:
+ *
+ * 1. The in-process KV store (`PMMemoryStore`) — analogous to reading the
+ *    PMLL memory silo (PMLL.c::init_silo / update_silo) for a cached result.
+ * 2. The Q-promise registry (`QPromiseRegistry`) — analogous to checking
+ *    whether a `QMemNode` chain is still in-flight (Q_promise_lib pending).
+ *
+ * If both layers miss, the caller is expected to proceed with the real tool
+ * call and then invoke `store.set(key, value)` to populate the cache for
+ * future agents.
+ */
+/**
+ * Check whether `key` is already resolved for `sessionId`.
+ *
+ * The function implements a two-stage guard:
+ *
+ * Stage 1 — KV store hit (PMLL silo cache):
+ *     If the key exists and is resolved, return the cached value
+ *     immediately.  This eliminates the need to re-invoke the
+ *     corresponding MCP tool entirely.
+ *
+ * Stage 2 — Q-promise pending check:
+ *     If the key is registered as an in-flight promise, return a
+ *     `pending` indicator so the caller can await resolution rather
+ *     than launching a duplicate tool call.
+ *
+ * Stage 3 — Full miss:
+ *     Neither layer has seen this key.  The caller should proceed with
+ *     the real MCP tool call and then call `store.set(key, value)`
+ *     to populate the cache.
+ *
+ * @param key              The context key to look up (e.g. a URL, task ID).
+ * @param sessionId        Identifies the current agent session (for logging).
+ * @param store            The session's `PMMemoryStore` instance.
+ * @param promiseRegistry  Shared `QPromiseRegistry` instance.
+ *
+ * @returns One of:
+ *   - `{ hit: true, value: string, index: number }`          — KV hit
+ *   - `{ hit: true, status: "pending", promise_id: string }` — in-flight
+ *   - `{ hit: false }`                                        — full miss
+ */
+export function peekContext(key, sessionId, store, promiseRegistry) {
+    // Stage 1: KV store check (PMLL silo read)
+    const [hit, value, index] = store.peek(key);
+    if (hit) {
+        return { hit: true, value: value, index: index };
+    }
+    // Stage 2: Q-promise in-flight check
+    const [found, status] = promiseRegistry.peekPromise(key);
+    if (found && status === "pending") {
+        return { hit: true, status: "pending", promise_id: key };
+    }
+    // Stage 3: Full miss — caller proceeds with the actual tool call
+    return { hit: false };
+}
+//# sourceMappingURL=peek.js.map

package/dist/peek.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peek.js","sourceRoot":"","sources":["../src/peek.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA0BH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,WAAW,CACzB,GAAW,EACX,SAAiB,EACjB,KAAoB,EACpB,eAAiC;IAEjC,2CAA2C;IAC3C,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5C,IAAI,GAAG,EAAE,CAAC;QACR,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,KAAM,EAAE,KAAK,EAAE,KAAM,EAAE,CAAC;IACrD,CAAC;IAED,qCAAqC;IACrC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,eAAe,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACzD,IAAI,KAAK,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;IAC3D,CAAC;IAED,iEAAiE;IACjE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AACxB,CAAC"}

package/dist/q-promise-bridge.d.ts

@@ -0,0 +1,58 @@
+/**
+ * q-promise-bridge.ts — Registry for in-flight Q-promise continuations.
+ *
+ * Mirrors the `QMemNode` singly-linked chain defined in
+ * `Q_promise_lib/Q_promises.h`:
+ *
+ *     typedef struct QMemNode {
+ *         long              index;
+ *         const char       *payload;
+ *         struct QMemNode  *next;
+ *     } QMemNode;
+ *
+ * In the C library a chain is traversed via `q_then(head, cb)`, invoking a
+ * callback for every node.  Here we model the same lifecycle in pure TypeScript:
+ * each promise starts as `"pending"` (`QMemNode.payload == NULL`) and
+ * transitions to `"resolved"` once `resolve()` is called with a payload.
+ *
+ * The `peekPromise()` method is a non-destructive status check — the
+ * TypeScript equivalent of walking the chain without modifying it.
+ */
+/** Result of a `peekPromise()` call: `[found, status, payload]`. */
+export type PeekPromiseResult = [boolean, string | null, string | null];
+/**
+ * In-process registry of Q-promise continuations.
+ *
+ * Provides the same lifecycle as the C `QMemNode` chain:
+ *   - `register()`     — allocate a new pending node
+ *   - `resolve()`      — write the payload (analogous to q_then callback)
+ *   - `peekPromise()`  — read status without consuming the entry
+ *
+ * Multiple sessions share a single registry; the `promiseId` is the
+ * caller's responsibility to namespace (e.g. `"{sessionId}:{key}"`).
+ */
+export declare class QPromiseRegistry {
+    private _promises;
+    /** Add a new pending promise (allocate a QMemNode with NULL payload). */
+    register(promiseId: string): void;
+    /**
+     * Mark `promiseId` as resolved with `payload`.
+     *
+     * Mirrors the `QThenCallback` being invoked for a node.
+     *
+     * @returns true if the promise existed and was resolved; false if unknown.
+     */
+    resolve(promiseId: string, payload: string): boolean;
+    /**
+     * Non-destructive status check.
+     *
+     * @returns `[found, status, payload]` — `found` is false when the promise
+     * ID is unknown.
+     */
+    peekPromise(promiseId: string): PeekPromiseResult;
+    get size(): number;
+    has(promiseId: string): boolean;
+    /** Exposed for testing: clear all promises. */
+    clear(): void;
+}
+//# sourceMappingURL=q-promise-bridge.d.ts.map

package/dist/q-promise-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"q-promise-bridge.d.ts","sourceRoot":"","sources":["../src/q-promise-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgBH,oEAAoE;AACpE,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;AAExE;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAAoC;IAMrD,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAQjC;;;;;;OAMG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAUpD;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,iBAAiB;IAYjD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI/B,+CAA+C;IAC/C,KAAK,IAAI,IAAI;CAGd"}

package/dist/q-promise-bridge.js

@@ -0,0 +1,88 @@
+/**
+ * q-promise-bridge.ts — Registry for in-flight Q-promise continuations.
+ *
+ * Mirrors the `QMemNode` singly-linked chain defined in
+ * `Q_promise_lib/Q_promises.h`:
+ *
+ *     typedef struct QMemNode {
+ *         long              index;
+ *         const char       *payload;
+ *         struct QMemNode  *next;
+ *     } QMemNode;
+ *
+ * In the C library a chain is traversed via `q_then(head, cb)`, invoking a
+ * callback for every node.  Here we model the same lifecycle in pure TypeScript:
+ * each promise starts as `"pending"` (`QMemNode.payload == NULL`) and
+ * transitions to `"resolved"` once `resolve()` is called with a payload.
+ *
+ * The `peekPromise()` method is a non-destructive status check — the
+ * TypeScript equivalent of walking the chain without modifying it.
+ */
+/**
+ * In-process registry of Q-promise continuations.
+ *
+ * Provides the same lifecycle as the C `QMemNode` chain:
+ *   - `register()`     — allocate a new pending node
+ *   - `resolve()`      — write the payload (analogous to q_then callback)
+ *   - `peekPromise()`  — read status without consuming the entry
+ *
+ * Multiple sessions share a single registry; the `promiseId` is the
+ * caller's responsibility to namespace (e.g. `"{sessionId}:{key}"`).
+ */
+export class QPromiseRegistry {
+    _promises = new Map();
+    // ------------------------------------------------------------------
+    // Core operations
+    // ------------------------------------------------------------------
+    /** Add a new pending promise (allocate a QMemNode with NULL payload). */
+    register(promiseId) {
+        this._promises.set(promiseId, {
+            promiseId,
+            status: "pending",
+            payload: null,
+        });
+    }
+    /**
+     * Mark `promiseId` as resolved with `payload`.
+     *
+     * Mirrors the `QThenCallback` being invoked for a node.
+     *
+     * @returns true if the promise existed and was resolved; false if unknown.
+     */
+    resolve(promiseId, payload) {
+        const promise = this._promises.get(promiseId);
+        if (promise === undefined) {
+            return false;
+        }
+        promise.status = "resolved";
+        promise.payload = payload;
+        return true;
+    }
+    /**
+     * Non-destructive status check.
+     *
+     * @returns `[found, status, payload]` — `found` is false when the promise
+     * ID is unknown.
+     */
+    peekPromise(promiseId) {
+        const promise = this._promises.get(promiseId);
+        if (promise === undefined) {
+            return [false, null, null];
+        }
+        return [true, promise.status, promise.payload];
+    }
+    // ------------------------------------------------------------------
+    // Introspection helpers
+    // ------------------------------------------------------------------
+    get size() {
+        return this._promises.size;
+    }
+    has(promiseId) {
+        return this._promises.has(promiseId);
+    }
+    /** Exposed for testing: clear all promises. */
+    clear() {
+        this._promises.clear();
+    }
+}
+//# sourceMappingURL=q-promise-bridge.js.map

package/dist/q-promise-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"q-promise-bridge.js","sourceRoot":"","sources":["../src/q-promise-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAmBH;;;;;;;;;;GAUG;AACH,MAAM,OAAO,gBAAgB;IACnB,SAAS,GAA0B,IAAI,GAAG,EAAE,CAAC;IAErD,qEAAqE;IACrE,kBAAkB;IAClB,qEAAqE;IAErE,yEAAyE;IACzE,QAAQ,CAAC,SAAiB;QACxB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,EAAE;YAC5B,SAAS;YACT,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,IAAI;SACd,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,SAAiB,EAAE,OAAe;QACxC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,CAAC,MAAM,GAAG,UAAU,CAAC;QAC5B,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,SAAiB;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,CAAC;IAED,qEAAqE;IACrE,wBAAwB;IACxB,qEAAqE;IAErE,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IAED,+CAA+C;IAC/C,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF"}

package/dist/solution-engine.d.ts

@@ -0,0 +1,54 @@
+/**
+ * solution-engine.ts — Context+ Solution Engine Processor for PMLL MCP.
+ *
+ * Integrates the Context+ semantic intelligence approach as the long-term
+ * memory and solution engine for the PMLL persistent memory logic loop.
+ *
+ * The solution engine:
+ *   1. Bridges short-term KV cache (existing 5 tools) with the long-term
+ *      memory graph (new 6 tools from Context+)
+ *   2. Provides a unified context resolution path: short-term → long-term
+ *   3. Auto-promotes frequently accessed short-term cache entries to the
+ *      long-term memory graph
+ *   4. Implements the Context+ decay scoring and similarity-based retrieval
+ *
+ * Designed to improve context retention and retrieval for coding agents by combining:
+ *   - Immediate context via KV cache (short-term)
+ *   - Long-term knowledge via the memory graph
+ *   - Semantic search across both layers
+ */
+import { PMMemoryStore } from "./kv-store.js";
+import { type NodeType } from "./memory-graph.js";
+/**
+ * Resolve context by checking both short-term (KV) and long-term (graph)
+ * memory layers. Returns the best match from either layer.
+ */
+export declare function resolveContext(sessionId: string, key: string, store: PMMemoryStore): {
+    source: "short_term" | "long_term" | "miss";
+    value: string | null;
+    score: number;
+};
+/**
+ * Promote a short-term KV entry to the long-term memory graph.
+ * This creates a persistent memory node from a frequently accessed cache entry.
+ */
+export declare function promoteToLongTerm(sessionId: string, key: string, value: string, nodeType?: NodeType, metadata?: Record<string, string>): {
+    promoted: boolean;
+    nodeId: string | null;
+};
+/**
+ * Get a unified status view of both short-term and long-term memory.
+ */
+export declare function getMemoryStatus(sessionId: string, store: PMMemoryStore): {
+    shortTerm: {
+        slots: number;
+        siloSize: number;
+    };
+    longTerm: {
+        nodes: number;
+        edges: number;
+        types: Record<string, number>;
+    };
+    promotionThreshold: number;
+};
+//# sourceMappingURL=solution-engine.d.ts.map

package/dist/solution-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solution-engine.d.ts","sourceRoot":"","sources":["../src/solution-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAIL,KAAK,QAAQ,EACd,MAAM,mBAAmB,CAAC;AAO3B;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,aAAa,GACnB;IAAE,MAAM,EAAE,YAAY,GAAG,WAAW,GAAG,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAmBtF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,QAAoB,EAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAG9C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,aAAa,GACnB;IACD,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IAC1E,kBAAkB,EAAE,MAAM,CAAC;CAC5B,CAeA"}

package/dist/solution-engine.js

@@ -0,0 +1,73 @@
+/**
+ * solution-engine.ts — Context+ Solution Engine Processor for PMLL MCP.
+ *
+ * Integrates the Context+ semantic intelligence approach as the long-term
+ * memory and solution engine for the PMLL persistent memory logic loop.
+ *
+ * The solution engine:
+ *   1. Bridges short-term KV cache (existing 5 tools) with the long-term
+ *      memory graph (new 6 tools from Context+)
+ *   2. Provides a unified context resolution path: short-term → long-term
+ *   3. Auto-promotes frequently accessed short-term cache entries to the
+ *      long-term memory graph
+ *   4. Implements the Context+ decay scoring and similarity-based retrieval
+ *
+ * Designed to improve context retention and retrieval for coding agents by combining:
+ *   - Immediate context via KV cache (short-term)
+ *   - Long-term knowledge via the memory graph
+ *   - Semantic search across both layers
+ */
+import { upsertNode, searchGraph, getGraphStats, } from "./memory-graph.js";
+// ---------------------------------------------------------------------------
+// Promotion threshold: entries accessed >= this count get promoted
+// ---------------------------------------------------------------------------
+const PROMOTION_THRESHOLD = 3;
+/**
+ * Resolve context by checking both short-term (KV) and long-term (graph)
+ * memory layers. Returns the best match from either layer.
+ */
+export function resolveContext(sessionId, key, store) {
+    // Layer 1: Short-term KV cache
+    const [hit, value] = store.peek(key);
+    if (hit && value !== null) {
+        return { source: "short_term", value, score: 1.0 };
+    }
+    // Layer 2: Long-term memory graph (semantic search)
+    const graphResult = searchGraph(sessionId, key, 1, 1);
+    if (graphResult.direct.length > 0) {
+        const top = graphResult.direct[0];
+        return {
+            source: "long_term",
+            value: top.node.content,
+            score: top.relevanceScore / 100,
+        };
+    }
+    return { source: "miss", value: null, score: 0 };
+}
+/**
+ * Promote a short-term KV entry to the long-term memory graph.
+ * This creates a persistent memory node from a frequently accessed cache entry.
+ */
+export function promoteToLongTerm(sessionId, key, value, nodeType = "concept", metadata) {
+    const node = upsertNode(sessionId, nodeType, key, value, metadata);
+    return { promoted: true, nodeId: node.id };
+}
+/**
+ * Get a unified status view of both short-term and long-term memory.
+ */
+export function getMemoryStatus(sessionId, store) {
+    const stats = getGraphStats(sessionId);
+    return {
+        shortTerm: {
+            slots: store.size,
+            siloSize: store.siloSize,
+        },
+        longTerm: {
+            nodes: stats.nodes,
+            edges: stats.edges,
+            types: stats.types,
+        },
+        promotionThreshold: PROMOTION_THRESHOLD,
+    };
+}
+//# sourceMappingURL=solution-engine.js.map

package/dist/solution-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solution-engine.js","sourceRoot":"","sources":["../src/solution-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EACL,UAAU,EACV,WAAW,EACX,aAAa,GAEd,MAAM,mBAAmB,CAAC;AAE3B,8EAA8E;AAC9E,mEAAmE;AACnE,8EAA8E;AAC9E,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAE9B;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAiB,EACjB,GAAW,EACX,KAAoB;IAEpB,+BAA+B;IAC/B,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,GAAG,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1B,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACrD,CAAC;IAED,oDAAoD;IACpD,MAAM,WAAW,GAAG,WAAW,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACtD,IAAI,WAAW,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAClC,OAAO;YACL,MAAM,EAAE,WAAW;YACnB,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO;YACvB,KAAK,EAAE,GAAG,CAAC,cAAc,GAAG,GAAG;SAChC,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAiB,EACjB,GAAW,EACX,KAAa,EACb,WAAqB,SAAS,EAC9B,QAAiC;IAEjC,MAAM,IAAI,GAAG,UAAU,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACnE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAiB,EACjB,KAAoB;IAMpB,MAAM,KAAK,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IAEvC,OAAO;QACL,SAAS,EAAE;YACT,KAAK,EAAE,KAAK,CAAC,IAAI;YACjB,QAAQ,EAAE,KAAK,CAAC,QAAQ;SACzB;QACD,QAAQ,EAAE;YACR,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB;QACD,kBAAkB,EAAE,mBAAmB;KACxC,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@drqedwards/pmll",
+  "version": "2.0.4",
+  "mcpName": "io.github.drqedwards/pmll-memory-mcp",
+  "description": "Persistent Memory Logic Loop (PMLL) MCP server. Short name for pmll-memory-mcp; npx pmll starts the server.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "pmll": "dist/index.js",
+    "pmll-memory-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "agent_instructions.md",
+    "benchmarks"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "pmll",
+    "memory",
+    "kv-store",
+    "q-promise",
+    "context-plus",
+    "memory-graph",
+    "semantic-search",
+    "solution-engine",
+    "agent-instructions",
+    "benchmarks",
+    "peek-cache"
+  ],
+  "author": "drQedwards",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/drQedwards/PPM.git"
+  },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/DrQedwards"
+    },
+    {
+      "type": "buymeacoffee",
+      "url": "https://buymeacoffee.com/drqedwards"
+    },
+    {
+      "type": "coingecko",
+      "url": "https://www.coingecko.com/en/portfolios/public/jkdrq"
+    }
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.1.4"
+  }
+}