@seanhogg/builderforce-memory 2026.6.18

package/src/agent/SSMAgent.ts

@@ -0,0 +1,327 @@
+/**
+ * SSMAgent – high-level orchestration primitive.
+ *
+ * Combines SSMRuntime (inference + adaptation), MemoryStore (persistent facts),
+ * and a conversation history manager into a single agent interface.
+ *
+ * Prompt format matches MambaChatbot so the SSM model can follow the same
+ * token patterns it was trained on:
+ *
+ *   System: <systemPrompt>
+ *   [Fact (<key>): <content>  ← injected by importance desc, filtered by tag/key]
+ *   User: <message>
+ *   Assistant: <message>
+ *   ...
+ *   User: <current input>
+ *   Assistant:
+ */
+
+import type { AdaptOptions, AdaptResult } from '../session/index.js';
+import type { SSMRuntime, GenerateOptions } from '../runtime/SSMRuntime.js';
+import type { MemoryStore, MemoryEntry } from '../memory/MemoryStore.js';
+import { SSMError } from '../errors/SSMError.js';
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export type MessageRole = 'user' | 'assistant' | 'system';
+
+export interface AgentMessage {
+    role   : MessageRole;
+    content: string;
+}
+
+export interface SSMAgentOptions {
+    /** The runtime to use for inference and adaptation. */
+    runtime          : SSMRuntime;
+    /** Optional memory store for persistent fact retrieval. */
+    memory?          : MemoryStore;
+    /** Default system prompt. Default: 'You are a helpful assistant.' */
+    systemPrompt?    : string;
+    /**
+     * Max user+assistant turn pairs to include in context.
+     * Oldest turns are dropped first.
+     * Default: 20
+     */
+    maxHistoryTurns? : number;
+    /**
+     * When true, the agent serialises its conversation history to memory
+     * under the `__history__` key on `destroy()`, and loads it back on
+     * construction if the key is present.
+     * Default: true
+     */
+    persistHistory?  : boolean;
+    /**
+     * How facts are picked from the MemoryStore for injection each turn:
+     *   - 'semantic'  (default): top-`maxFacts` by SSM-embedding similarity to
+     *     the input (`recallSimilar`) — injects the few *relevant* facts, which
+     *     keeps the prompt small and is paraphrase-robust.
+     *   - 'substring': legacy behaviour — only facts whose key literally appears
+     *     in the input.
+     * `injectAllFacts` on a turn overrides this and injects everything.
+     */
+    factSelection?   : 'semantic' | 'substring';
+    /** Max facts injected in 'semantic' mode. Default: 8. */
+    maxFacts?        : number;
+}
+
+export interface ThinkOptions extends GenerateOptions {
+    /** Override the system prompt for this single turn only. */
+    systemPrompt?: string;
+    /**
+     * Inject all recalled facts into the context for this turn.
+     * Default: false — only facts whose keys appear in the input are injected.
+     */
+    injectAllFacts?: boolean;
+}
+
+/** Key used to persist conversation history in the MemoryStore. */
+const HISTORY_KEY = '__history__';
+
+// ── SSMAgent ──────────────────────────────────────────────────────────────────
+
+export class SSMAgent {
+    private readonly _runtime         : SSMRuntime;
+    private readonly _memory          : MemoryStore | undefined;
+    private readonly _systemPrompt    : string;
+    private readonly _maxHistoryTurns : number;
+    private readonly _persistHistory  : boolean;
+    private readonly _factSelection   : 'semantic' | 'substring';
+    private readonly _maxFacts        : number;
+    private _history: AgentMessage[] = [];
+
+    constructor(opts: SSMAgentOptions) {
+        this._runtime         = opts.runtime;
+        this._memory          = opts.memory;
+        this._systemPrompt    = opts.systemPrompt    ?? 'You are a helpful assistant.';
+        this._maxHistoryTurns = opts.maxHistoryTurns ?? 20;
+        this._persistHistory  = opts.persistHistory  ?? true;
+        this._factSelection   = opts.factSelection   ?? 'semantic';
+        this._maxFacts        = opts.maxFacts         ?? 8;
+    }
+
+    /**
+     * Initialises the agent, loading persisted history from memory if available.
+     * Call this after construction when `persistHistory` is enabled and a memory
+     * store is present.
+     */
+    async init(): Promise<void> {
+        if (this._persistHistory && this._memory) {
+            try {
+                const entry = await this._memory.recall(HISTORY_KEY);
+                if (entry) {
+                    const parsed = JSON.parse(entry.content) as AgentMessage[];
+                    if (Array.isArray(parsed)) {
+                        this._history = parsed;
+                    }
+                }
+            } catch {
+                // Corrupted or missing history — start fresh
+                this._history = [];
+            }
+        }
+    }
+
+    // ── Inference ─────────────────────────────────────────────────────────────
+
+    /**
+     * Sends a user message and returns the full assistant response.
+     * Routes through InferenceRouter — may use SSM or transformer bridge.
+     * Appends both user and assistant turns to history.
+     */
+    async think(input: string, opts: ThinkOptions = {}): Promise<string> {
+        const { systemPrompt, injectAllFacts, ...generateOpts } = opts;
+        const { system, conversation } = await this._buildPrompt(input, systemPrompt, injectAllFacts);
+
+        const raw = await this._runtime.generate(conversation, {
+            maxNewTokens: 200,
+            temperature : 0.7,
+            topK        : 50,
+            topP        : 0.9,
+            system,
+            ...generateOpts,
+        });
+
+        // Trim any additional turns the model may have hallucinated
+        const response = raw.split('\nUser:')[0].trim();
+
+        this._appendHistory(input, response);
+        return response;
+    }
+
+    /**
+     * Streaming variant of `think()`.
+     * Always uses the SSM path (consistent low-latency streaming).
+     * Appends history after the stream completes.
+     */
+    async *thinkStream(input: string, opts: ThinkOptions = {}): AsyncIterable<string> {
+        const { systemPrompt, injectAllFacts, bridgeOpts: _b, ...completeOpts } = opts;
+        const { system, conversation } = await this._buildPrompt(input, systemPrompt, injectAllFacts);
+
+        let full = '';
+        for await (const token of this._runtime.stream(conversation, {
+            maxNewTokens: 200,
+            temperature : 0.7,
+            topK        : 50,
+            topP        : 0.9,
+            system,
+            ...completeOpts,
+        })) {
+            full += token;
+            yield token;
+        }
+
+        const response = full.split('\nUser:')[0].trim();
+        this._appendHistory(input, response);
+    }
+
+    // ── Adaptation ────────────────────────────────────────────────────────────
+
+    /**
+     * Fine-tunes the SSM on the provided text.
+     * Pass-through to runtime.adapt().
+     */
+    async learn(data: string, opts?: AdaptOptions): Promise<AdaptResult> {
+        return this._runtime.adapt(data, opts);
+    }
+
+    // ── Memory ────────────────────────────────────────────────────────────────
+
+    /**
+     * Stores a fact in the MemoryStore.
+     * Throws SSMError('MEMORY_UNAVAILABLE') if no MemoryStore was provided.
+     */
+    async remember(key: string, fact: string): Promise<void> {
+        if (!this._memory) {
+            throw new SSMError(
+                'MEMORY_UNAVAILABLE',
+                'SSMAgent was constructed without a MemoryStore. Pass `memory` in SSMAgentOptions.',
+            );
+        }
+        await this._memory.remember(key, fact);
+    }
+
+    /**
+     * Retrieves a fact from the MemoryStore.
+     * Returns `undefined` if key not found or no MemoryStore was provided.
+     */
+    async recall(key: string): Promise<string | undefined> {
+        if (!this._memory) return undefined;
+        const entry = await this._memory.recall(key);
+        return entry?.content;
+    }
+
+    // ── History ───────────────────────────────────────────────────────────────
+
+    /** Clears all conversation history. Does not affect MemoryStore. */
+    clearHistory(): void {
+        this._history = [];
+    }
+
+    /** Number of complete user+assistant turn pairs. */
+    get turnCount(): number {
+        return Math.floor(this._history.length / 2);
+    }
+
+    /** Read-only snapshot of the current conversation history. */
+    get history(): readonly AgentMessage[] {
+        return this._history;
+    }
+
+    // ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    /**
+     * Persists conversation history to memory (if `persistHistory` is true and
+     * a MemoryStore is available) and destroys the underlying runtime.
+     */
+    async destroy(): Promise<void> {
+        if (this._persistHistory && this._memory && this._history.length > 0) {
+            try {
+                await this._memory.remember(HISTORY_KEY, JSON.stringify(this._history));
+            } catch {
+                // Persistence failure is non-fatal
+            }
+        }
+        this._runtime.destroy();
+    }
+
+    // ── Private helpers ───────────────────────────────────────────────────────
+
+    /**
+     * Selects which stored facts to inject for this turn:
+     *   - injectAllFacts → every fact
+     *   - 'semantic'     → top-`maxFacts` by SSM-embedding similarity to the input
+     *                      (recallSimilar; falls back to lexical overlap when the
+     *                      runtime can't embed) — small, relevant, paraphrase-robust
+     *   - 'substring'    → legacy key-substring match
+     */
+    private async _selectFacts(input: string, injectAllFacts?: boolean): Promise<MemoryEntry[]> {
+        const memory = this._memory!;
+        if (injectAllFacts) return memory.recallAll();
+        if (this._factSelection === 'semantic') {
+            return memory.recallSimilar(input, this._maxFacts, this._runtime);
+        }
+        return (await memory.recallAll()).filter(f => input.includes(f.key));
+    }
+
+    /**
+     * Builds the prompt as two parts split at the cache boundary:
+     *   - `system`       : the System line + injected Facts — stable across a
+     *                      turn, so the transformer can cache it (see
+     *                      SSMRuntime.GenerateOptions.system).
+     *   - `conversation` : trimmed history + the current User turn — volatile,
+     *                      regenerated every turn.
+     *
+     * Joining them with a newline (which SSMRuntime does on the SSM path)
+     * reproduces the original single-string MambaChatbot format exactly, so the
+     * SSM sees an unchanged prompt.
+     */
+    private async _buildPrompt(
+        input                : string,
+        systemPromptOverride?: string,
+        injectAllFacts?      : boolean,
+    ): Promise<{ system: string; conversation: string }> {
+        const sys         = systemPromptOverride ?? this._systemPrompt;
+        const systemLines : string[] = [`System: ${sys}`];
+
+        // Inject relevant facts from MemoryStore, sorted by importance descending
+        if (this._memory) {
+            const relevant = (await this._selectFacts(input, injectAllFacts))
+                // Never inject the serialised conversation-history blob as a fact.
+                .filter(f => f.key !== HISTORY_KEY);
+
+            // Sort by importance descending (missing importance defaults to 0.5)
+            const sorted = relevant.slice().sort(
+                (a, b) => (b.importance ?? 0.5) - (a.importance ?? 0.5),
+            );
+
+            for (const fact of sorted) {
+                systemLines.push(`Fact (${fact.key}): ${fact.content}`);
+            }
+        }
+
+        // Trim history to maxHistoryTurns pairs (oldest first)
+        const maxMessages = this._maxHistoryTurns * 2;
+        const trimmed = this._history.length > maxMessages
+            ? this._history.slice(this._history.length - maxMessages)
+            : this._history;
+
+        const convoLines: string[] = [];
+        for (const msg of trimmed) {
+            const speaker = msg.role === 'user' ? 'User' : 'Assistant';
+            convoLines.push(`${speaker}: ${msg.content}`);
+        }
+
+        convoLines.push(`User: ${input}`);
+        convoLines.push('Assistant:');
+
+        return {
+            system      : systemLines.join('\n'),
+            conversation: convoLines.join('\n'),
+        };
+    }
+
+    private _appendHistory(input: string, response: string): void {
+        this._history.push({ role: 'user',      content: input    });
+        this._history.push({ role: 'assistant', content: response });
+    }
+}

package/src/agent/index.ts

@@ -0,0 +1,2 @@
+export { SSMAgent } from './SSMAgent.js';
+export type { SSMAgentOptions, ThinkOptions, AgentMessage, MessageRole } from './SSMAgent.js';

package/src/bridges/AnthropicBridge.ts

@@ -0,0 +1,166 @@
+/**
+ * AnthropicBridge – TransformerBridge implementation for the Anthropic Messages API.
+ *
+ * Uses the /v1/messages endpoint.  System prompts are passed as the top-level
+ * `system` field (not a message role), per the Anthropic spec.
+ */
+
+import { SSMError } from '../errors/SSMError.js';
+import type { TransformerBridge, BridgeGenerateOptions } from './TransformerBridge.js';
+
+export interface AnthropicBridgeOptions {
+    /** Anthropic API key. */
+    apiKey        : string;
+    /**
+     * Model to use. Default: 'claude-haiku-4-5' (cheapest current model:
+     * $1/1M input, $5/1M output). The previous default `claude-3-5-haiku-*`
+     * was retired on 2026-02-19 and now 404s.
+     */
+    model?        : string;
+    /** Anthropic API version header. Default: '2023-06-01'. */
+    apiVersion?   : string;
+    /** Default system prompt. Default: none. */
+    systemPrompt? : string;
+    /** Default max tokens — required by Anthropic. Default: 1024. */
+    maxTokens?    : number;
+    /**
+     * When true (default), the system prompt is sent as a cacheable content
+     * block (`cache_control: {type: 'ephemeral'}`). Prompt caching bills cache
+     * reads at ~10% of the input price, so a stable system prefix reused across
+     * turns is up to ~90% cheaper on its input tokens. Caching only engages once
+     * the cached prefix exceeds the model minimum (~4096 tokens for Haiku 4.5);
+     * below that it is a silent no-op, never an error. Set false to opt out.
+     */
+    cacheSystem?  : boolean;
+}
+
+const API_URL = 'https://api.anthropic.com/v1/messages';
+
+export class AnthropicBridge implements TransformerBridge {
+    readonly supportsStreaming = true as const;
+
+    private readonly _apiKey      : string;
+    private readonly _model       : string;
+    private readonly _apiVersion  : string;
+    private readonly _systemPrompt: string;
+    private readonly _maxTokens   : number;
+    private readonly _cacheSystem : boolean;
+
+    constructor(opts: AnthropicBridgeOptions) {
+        this._apiKey       = opts.apiKey;
+        this._model        = opts.model      ?? 'claude-haiku-4-5';
+        this._apiVersion   = opts.apiVersion ?? '2023-06-01';
+        this._systemPrompt = opts.systemPrompt ?? '';
+        this._maxTokens    = opts.maxTokens    ?? 1024;
+        this._cacheSystem  = opts.cacheSystem  ?? true;
+    }
+
+    async generate(prompt: string, opts: BridgeGenerateOptions = {}): Promise<string> {
+        const body = this._buildBody(prompt, opts, false);
+        const res  = await this._fetch(body);
+
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new SSMError(
+                'BRIDGE_REQUEST_FAILED',
+                `Anthropic API returned ${res.status}: ${text}`,
+            );
+        }
+
+        const json    = await res.json() as Record<string, unknown>;
+        const content = (json as any).content?.[0]?.text;
+        if (typeof content !== 'string') {
+            throw new SSMError('BRIDGE_RESPONSE_INVALID', 'Unexpected Anthropic response shape.');
+        }
+        return content;
+    }
+
+    async *stream(prompt: string, opts: BridgeGenerateOptions = {}): AsyncIterable<string> {
+        const body = this._buildBody(prompt, opts, true);
+        const res  = await this._fetch(body);
+
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new SSMError(
+                'BRIDGE_REQUEST_FAILED',
+                `Anthropic streaming API returned ${res.status}: ${text}`,
+            );
+        }
+
+        if (!res.body) {
+            throw new SSMError('BRIDGE_RESPONSE_INVALID', 'Anthropic streaming response has no body.');
+        }
+
+        yield* parseAnthropicStream(res.body);
+    }
+
+    private _buildBody(prompt: string, opts: BridgeGenerateOptions, stream: boolean): string {
+        const sys = opts.systemPrompt ?? this._systemPrompt;
+        const body: Record<string, unknown> = {
+            model     : opts.model     ?? this._model,
+            max_tokens: opts.maxTokens ?? this._maxTokens,
+            messages  : [{ role: 'user', content: prompt }],
+        };
+        if (sys) {
+            // Caching is a prefix match: render the stable system prompt as a
+            // single cache-marked content block so reads on subsequent turns are
+            // billed at ~10% of input price. The volatile user message is sent
+            // unmarked after it, so it never enters the cached prefix.
+            body['system'] = this._cacheSystem
+                ? [{ type: 'text', text: sys, cache_control: { type: 'ephemeral' } }]
+                : sys;
+        }
+        if (stream) body['stream'] = true;
+        return JSON.stringify(body);
+    }
+
+    private _fetch(body: string): Promise<Response> {
+        return fetch(API_URL, {
+            method : 'POST',
+            headers: {
+                'Content-Type'      : 'application/json',
+                'x-api-key'         : this._apiKey,
+                'anthropic-version' : this._apiVersion,
+            },
+            body,
+        });
+    }
+}
+
+// ── SSE parser (Anthropic event format) ──────────────────────────────────────
+
+async function* parseAnthropicStream(body: ReadableStream<Uint8Array>): AsyncIterable<string> {
+    const reader  = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer    = '';
+
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() as string; // split() always yields ≥1 element → never undefined
+
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed.startsWith('data: ')) continue;
+
+                const data = trimmed.slice(6);
+                try {
+                    const event = JSON.parse(data) as Record<string, unknown>;
+                    // content_block_delta events carry the streamed text
+                    if (event['type'] === 'content_block_delta') {
+                        const text = (event as any).delta?.text;
+                        if (typeof text === 'string' && text.length > 0) yield text;
+                    }
+                } catch {
+                    // Skip malformed SSE lines
+                }
+            }
+        }
+    } finally {
+        reader.releaseLock();
+    }
+}

package/src/bridges/CachingBridge.ts

@@ -0,0 +1,79 @@
+/**
+ * CachingBridge – a read-through caching decorator for any TransformerBridge.
+ *
+ * Wraps an inner bridge and memoises `generate()` keyed on the full request
+ * shape (model, system, prompt, sampling). Identical completions are served
+ * from memory instead of re-billing the provider — the single most effective
+ * lever for cutting LLM spend on repeated prompts (distillation passes, retries,
+ * fan-out over duplicate inputs).
+ *
+ * Composes with every bridge, so the caching policy lives in one place rather
+ * than being reimplemented per provider:
+ *
+ *   const bridge = new CachingBridge(new AnthropicBridge({ apiKey }));
+ *
+ * Streaming is delegated straight through and never cached — a token stream is
+ * consumed once and caching it would defeat its purpose.
+ */
+
+import type { TransformerBridge, BridgeGenerateOptions } from './TransformerBridge.js';
+import { ResponseCache, buildCacheKey, type ResponseCacheOptions } from './ResponseCache.js';
+
+export interface CachingBridgeOptions extends ResponseCacheOptions {
+    /**
+     * Provide a shared ResponseCache instance instead of letting the bridge
+     * create its own. Use this to share one cache across multiple bridges, or
+     * to inspect/clear the cache from outside.
+     */
+    cache? : ResponseCache;
+}
+
+export class CachingBridge implements TransformerBridge {
+    private readonly _inner : TransformerBridge;
+    private readonly _cache : ResponseCache;
+
+    constructor(inner: TransformerBridge, opts: CachingBridgeOptions = {}) {
+        this._inner = inner;
+        this._cache = opts.cache ?? new ResponseCache(opts);
+    }
+
+    /** Mirrors the wrapped bridge so callers can still gate on streaming support. */
+    get supportsStreaming(): boolean {
+        return this._inner.supportsStreaming;
+    }
+
+    /** The underlying cache — exposed for stats inspection and manual eviction. */
+    get cache(): ResponseCache {
+        return this._cache;
+    }
+
+    async generate(prompt: string, opts: BridgeGenerateOptions = {}): Promise<string> {
+        const key = buildCacheKey({
+            prompt,
+            model       : opts.model,
+            systemPrompt : opts.systemPrompt,
+            maxTokens   : opts.maxTokens,
+            temperature : opts.temperature,
+            topP        : opts.topP,
+        });
+
+        const cached = this._cache.get(key);
+        if (cached !== undefined) return cached;
+
+        const value = await this._inner.generate(prompt, opts);
+        this._cache.set(key, value, Date.now());
+        return value;
+    }
+
+    /**
+     * Streaming is delegated to the inner bridge unchanged and is never cached.
+     * Present only when the inner bridge supports it, so `supportsStreaming`
+     * stays an accurate gate.
+     */
+    stream(prompt: string, opts?: BridgeGenerateOptions): AsyncIterable<string> {
+        if (!this._inner.stream) {
+            throw new Error('Wrapped bridge does not support streaming.');
+        }
+        return this._inner.stream(prompt, opts);
+    }
+}

package/src/bridges/FetchBridge.ts

@@ -0,0 +1,41 @@
+/**
+ * FetchBridge – generic OpenAI-compatible bridge for local or hosted endpoints.
+ *
+ * Works with Ollama, LM Studio, vLLM, llama.cpp server, or any service that
+ * exposes a /chat/completions endpoint compatible with the OpenAI request
+ * and response schema.
+ */
+
+import { OpenAIBridge } from './OpenAIBridge.js';
+import type { BridgeGenerateOptions } from './TransformerBridge.js';
+
+export interface FetchBridgeOptions {
+    /** Base URL of the OpenAI-compatible server, e.g. 'http://localhost:1234/v1'. */
+    baseUrl       : string;
+    /** API key — many local servers require any non-empty string. Default: 'local'. */
+    apiKey?       : string;
+    /** Model name understood by the server. Default: 'default'. */
+    model?        : string;
+    /** Default system prompt. */
+    systemPrompt? : string;
+    /** Default max tokens. Default: 512. */
+    maxTokens?    : number;
+}
+
+/**
+ * FetchBridge is a thin re-configuration of OpenAIBridge pointed at a custom
+ * base URL.  All streaming and request logic is inherited.
+ */
+export class FetchBridge extends OpenAIBridge {
+    constructor(opts: FetchBridgeOptions) {
+        super({
+            apiKey       : opts.apiKey        ?? 'local',
+            model        : opts.model         ?? 'default',
+            baseUrl      : opts.baseUrl,
+            systemPrompt : opts.systemPrompt,
+            maxTokens    : opts.maxTokens,
+        });
+    }
+}
+
+export type { BridgeGenerateOptions };