@atomicmemory/core 1.0.0

package/dist/services/llm.js

@@ -0,0 +1,265 @@
+/**
+ * LLM provider abstraction for chat completions.
+ * Supports OpenAI, Ollama, and any OpenAI-compatible API (LM Studio, etc).
+ * Provider is selected via PROVIDER_LLM env var.
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import OpenAI from 'openai';
+import { Agent as UndiciAgent } from 'undici';
+import { retryOnRateLimit } from './api-retry.js';
+import { estimateCostUsd, getCostStage, summarizeUsage, writeCostEvent, } from './cost-telemetry.js';
+import { ClaudeCodeLLM } from './claude-code-llm.js';
+let llmConfig = null;
+/** Bind the LLM module's config. Called once by the composition root. */
+export function initLlm(config) {
+    llmConfig = config;
+    provider = null;
+    providerKey = '';
+}
+function requireConfig() {
+    if (!llmConfig) {
+        throw new Error('llm.ts: initLlm(config) must be called at composition-root time before chat. See runtime-container.ts.');
+    }
+    return llmConfig;
+}
+/** Extended-timeout dispatcher for slow local models (e.g. qwen3 thinking mode). */
+const ollamaDispatcher = new UndiciAgent({ headersTimeout: 300_000, bodyTimeout: 300_000 });
+function sanitizeTransportContent(content, aggressive = false) {
+    const normalized = content.normalize('NFKC');
+    const cleaned = Array.from(normalized).map((char) => {
+        const codePoint = char.codePointAt(0) ?? 0;
+        const isAllowedWhitespace = char === '\n' || char === '\r' || char === '\t';
+        const isControl = codePoint < 0x20 && !isAllowedWhitespace;
+        const isDelete = codePoint === 0x7f;
+        if (isControl || isDelete)
+            return ' ';
+        if (!aggressive)
+            return char;
+        if (codePoint >= 0x20 && codePoint <= 0x7e)
+            return char;
+        if (/\p{Letter}|\p{Number}/u.test(char))
+            return char;
+        return ' ';
+    }).join('');
+    return cleaned.replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+}
+function sanitizeMessages(messages, aggressive = false) {
+    return messages.map((message) => ({
+        ...message,
+        content: sanitizeTransportContent(message.content, aggressive),
+    }));
+}
+function isJsonBodyParseError(error) {
+    if (!(error instanceof Error))
+        return false;
+    return error.message.includes('parse the JSON body of your request');
+}
+/** OpenAI and any OpenAI-compatible API (LM Studio at localhost:1234/v1, etc). */
+class OpenAICompatibleLLM {
+    client;
+    model;
+    constructor(apiKey, model, baseURL) {
+        this.client = new OpenAI({ apiKey, baseURL });
+        this.model = model;
+    }
+    async chat(messages, options = {}) {
+        try {
+            return await this.executeOpenAIRequest(messages, options, false);
+        }
+        catch (error) {
+            if (!isJsonBodyParseError(error))
+                throw error;
+            return this.executeOpenAIRequest(messages, options, true);
+        }
+    }
+    /** Execute a single OpenAI-compatible request with optional aggressive sanitization. */
+    async executeOpenAIRequest(messages, options, aggressiveSanitize) {
+        const effectiveSeed = options.seed ?? requireConfig().llmSeed;
+        const request = () => this.client.chat.completions.create({
+            model: this.model,
+            messages: sanitizeMessages(messages, aggressiveSanitize),
+            temperature: options.temperature ?? 0,
+            max_tokens: options.maxTokens,
+            ...(options.jsonMode ? { response_format: { type: 'json_object' } } : {}),
+            ...(effectiveSeed !== undefined ? { seed: effectiveSeed } : {}),
+        });
+        const started = performance.now();
+        const response = await retryOnRateLimit(request);
+        recordOpenAICost(this.model, response.usage, started);
+        return response.choices[0].message.content ?? '';
+    }
+}
+/** Record cost telemetry for an OpenAI-compatible response. */
+function recordOpenAICost(model, responseUsage, started) {
+    const config = requireConfig();
+    const usage = summarizeUsage(responseUsage?.prompt_tokens ?? null, responseUsage?.completion_tokens ?? null, responseUsage?.total_tokens ?? null);
+    writeCostEvent({
+        stage: getCostStage(), provider: config.llmProvider, model, requestKind: 'chat',
+        durationMs: performance.now() - started, cacheHit: false,
+        inputTokens: usage.inputTokens ?? null, outputTokens: usage.outputTokens ?? null,
+        totalTokens: usage.totalTokens ?? null, estimatedCostUsd: estimateCostUsd(config.llmProvider, model, usage),
+    }, config);
+}
+/** Ollama via its native HTTP API at localhost:11434. */
+class OllamaLLM {
+    baseUrl;
+    model;
+    constructor(model, baseUrl = 'http://localhost:11434') {
+        this.baseUrl = baseUrl;
+        this.model = model;
+    }
+    async chat(messages, options = {}) {
+        const config = requireConfig();
+        const effectiveSeed = options.seed ?? config.llmSeed;
+        const body = {
+            model: this.model,
+            messages,
+            stream: false,
+            think: false,
+            options: {
+                temperature: options.temperature ?? 0,
+                ...(options.maxTokens ? { num_predict: options.maxTokens } : {}),
+                ...(effectiveSeed !== undefined ? { seed: effectiveSeed } : {}),
+            },
+            ...(options.jsonMode ? { format: 'json' } : {}),
+        };
+        const started = performance.now();
+        const response = await fetch(`${this.baseUrl}/api/chat`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(300_000),
+            // @ts-expect-error -- Node.js fetch supports undici dispatcher option
+            dispatcher: ollamaDispatcher,
+        });
+        if (!response.ok) {
+            throw new Error(`Ollama chat failed (${response.status}): ${await response.text()}`);
+        }
+        const data = await response.json();
+        const usage = summarizeUsage(data.prompt_eval_count ?? null, data.eval_count ?? null, null);
+        writeCostEvent({ stage: getCostStage(), provider: config.llmProvider, model: this.model, requestKind: 'chat', durationMs: performance.now() - started, cacheHit: false, inputTokens: usage.inputTokens ?? null, outputTokens: usage.outputTokens ?? null, totalTokens: usage.totalTokens ?? null, estimatedCostUsd: estimateCostUsd(config.llmProvider, this.model, usage) }, config);
+        const content = stripThinkingTags(data.message.content);
+        // Reasoning models (qwen3) put output in 'thinking' when content is empty.
+        if (!content && data.message.thinking) {
+            return stripThinkingTags(data.message.thinking);
+        }
+        return content;
+    }
+}
+/** Strip <think>...</think> tags that reasoning models (e.g. qwen3) emit. */
+function stripThinkingTags(text) {
+    return text.replace(/<think>[\s\S]*?<\/think>\s*/g, '').trim();
+}
+/** Anthropic Claude API. */
+class AnthropicLLM {
+    client;
+    model;
+    constructor(apiKey, model) {
+        this.client = new Anthropic({ apiKey });
+        this.model = model;
+    }
+    async chat(messages, options = {}) {
+        const config = requireConfig();
+        const systemMsg = messages.find((m) => m.role === 'system');
+        const nonSystemMsgs = messages
+            .filter((m) => m.role !== 'system')
+            .map((m) => ({ role: m.role, content: m.content }));
+        const request = () => this.client.messages.create({
+            model: this.model,
+            max_tokens: options.maxTokens ?? 1024,
+            temperature: options.temperature ?? 0,
+            ...(systemMsg ? { system: systemMsg.content } : {}),
+            messages: nonSystemMsgs,
+        });
+        const started = performance.now();
+        const response = await retryOnRateLimit(request);
+        const usage = summarizeUsage(response.usage?.input_tokens ?? null, response.usage?.output_tokens ?? null, null);
+        writeCostEvent({ stage: getCostStage(), provider: config.llmProvider, model: this.model, requestKind: 'chat', durationMs: performance.now() - started, cacheHit: false, inputTokens: usage.inputTokens ?? null, outputTokens: usage.outputTokens ?? null, totalTokens: usage.totalTokens ?? null, estimatedCostUsd: estimateCostUsd(config.llmProvider, this.model, usage) }, config);
+        const textBlock = response.content.find((b) => b.type === 'text');
+        const raw = textBlock?.text ?? '';
+        // Strip <thinking> tags that some models produce in their text output
+        return raw.replace(/<thinking>[\s\S]*?<\/thinking>\s*/g, '').trim();
+    }
+}
+/** Create LLM provider from config. */
+export function createLLMProvider() {
+    const config = requireConfig();
+    switch (config.llmProvider) {
+        case 'openai':
+            return new OpenAICompatibleLLM(config.openaiApiKey, config.llmModel);
+        case 'ollama':
+            return new OllamaLLM(config.llmModel, config.ollamaBaseUrl);
+        case 'groq':
+            return new OpenAICompatibleLLM(config.groqApiKey ?? '', config.llmModel, 'https://api.groq.com/openai/v1');
+        case 'anthropic':
+            return new AnthropicLLM(config.anthropicApiKey ?? '', config.llmModel);
+        case 'google-genai':
+            return new OpenAICompatibleLLM(config.googleApiKey ?? '', config.llmModel, 'https://generativelanguage.googleapis.com/v1beta/openai/');
+        case 'claude-code':
+            return new ClaudeCodeLLM({
+                llmProvider: config.llmProvider,
+                llmModel: config.llmModel,
+                costLoggingEnabled: config.costLoggingEnabled,
+                costRunId: config.costRunId,
+                costLogDir: config.costLogDir,
+            });
+        case 'openai-compatible':
+            return new OpenAICompatibleLLM(config.llmApiKey ?? config.openaiApiKey, config.llmModel, config.llmApiUrl);
+        default:
+            throw new Error(`Unknown LLM provider: ${config.llmProvider}`);
+    }
+}
+let provider = null;
+let providerKey = '';
+function getProviderKey() {
+    const config = requireConfig();
+    return [
+        config.llmProvider,
+        config.llmModel,
+        config.llmApiUrl ?? '',
+        config.ollamaBaseUrl,
+    ].join('|');
+}
+function getProvider() {
+    const nextKey = getProviderKey();
+    if (!provider || nextKey !== providerKey) {
+        provider = createLLMProvider();
+        providerKey = nextKey;
+    }
+    return provider;
+}
+/** Singleton-like LLM accessor that refreshes when runtime config changes. */
+export const llm = {
+    chat(messages, options) {
+        return getProvider().chat(messages, options);
+    },
+};
+/**
+ * Invoke an Anthropic model in forced tool-use mode and return the parsed
+ * tool input. Uses the module-local config (set by initLlm) for the API key.
+ *
+ * @param model   - Anthropic model ID (e.g. 'claude-sonnet-4-5').
+ * @param system  - System prompt.
+ * @param user    - User message.
+ * @param toolSchema - Tool definition; the model is forced to call this tool.
+ * @returns Parsed tool input cast to T.
+ */
+export async function callAnthropicTool(model, system, user, toolSchema) {
+    const cfg = requireConfig();
+    const client = new Anthropic({ apiKey: cfg.anthropicApiKey ?? cfg.llmApiKey ?? '' });
+    const response = await client.messages.create({
+        model,
+        max_tokens: 4096,
+        system,
+        messages: [{ role: 'user', content: user }],
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        tools: [toolSchema],
+        tool_choice: { type: 'tool', name: toolSchema.name },
+    });
+    for (const block of response.content) {
+        if (block.type === 'tool_use' && block.name === toolSchema.name) {
+            return block.input;
+        }
+    }
+    throw new Error(`Anthropic tool-use returned no ${toolSchema.name} block`);
+}

package/dist/services/memcell-projection.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Deterministic projection helpers for dual-write memory cells.
+ * These helpers keep retrieval-oriented child rows aligned with the parent
+ * memory projection without adding a second LLM step yet.
+ */
+import type { AtomicFactProjection, FactInput, ForesightProjection } from './memory-service-types.js';
+/**
+ * Build the retrieval-facing atomic fact row for a parent memory.
+ * Current prototype uses one canonical fact row per stored fact; later work can
+ * expand this to multiple child facts per narrative episode.
+ */
+export declare function buildAtomicFactProjection(fact: FactInput, embedding: number[]): AtomicFactProjection;
+/**
+ * Derive initial foresight rows from plan-like facts.
+ * This is intentionally conservative: only explicit plan facts are projected.
+ */
+export declare function buildForesightProjections(fact: FactInput, embedding: number[]): ForesightProjection[];

package/dist/services/memcell-projection.js

@@ -0,0 +1,41 @@
+/**
+ * Deterministic projection helpers for dual-write memory cells.
+ * These helpers keep retrieval-oriented child rows aligned with the parent
+ * memory projection without adding a second LLM step yet.
+ */
+/**
+ * Build the retrieval-facing atomic fact row for a parent memory.
+ * Current prototype uses one canonical fact row per stored fact; later work can
+ * expand this to multiple child facts per narrative episode.
+ */
+export function buildAtomicFactProjection(fact, embedding) {
+    return {
+        factText: fact.fact,
+        embedding,
+        factType: fact.type,
+        importance: fact.importance,
+        keywords: fact.keywords,
+        metadata: {
+            headline: fact.headline,
+            entities: fact.entities,
+            relations: fact.relations,
+        },
+    };
+}
+/**
+ * Derive initial foresight rows from plan-like facts.
+ * This is intentionally conservative: only explicit plan facts are projected.
+ */
+export function buildForesightProjections(fact, embedding) {
+    if (fact.type !== 'plan')
+        return [];
+    return [{
+            content: fact.fact,
+            embedding,
+            foresightType: 'plan',
+            metadata: {
+                headline: fact.headline,
+                keywords: fact.keywords,
+            },
+        }];
+}

package/dist/services/memory-audn.d.ts

@@ -0,0 +1,43 @@
+/**
+ * AUDN (Add/Update/Delete/Noop) decision resolution and mutation execution.
+ * Handles fast-path AUDN, deferred AUDN, conflict candidate discovery,
+ * and the full mutation pipeline (update, supersede, delete canonical facts).
+ */
+import { type ClaimSlotInput } from '../db/claim-repository.js';
+import { type AUDNDecision } from './extraction.js';
+import { type CandidateMemory } from './conflict-policy.js';
+import type { AudnFactContext, FactInput, FactResult, IngestTraceCandidate, MemoryServiceDeps, Outcome } from './memory-service-types.js';
+export interface AudnTraceContext {
+    fact: FactInput;
+    logicalTimestamp?: Date;
+    writeSecurity: {
+        allowed: boolean;
+        blockedBy: string | null;
+        trust: {
+            score: number;
+        };
+    };
+    entropyResult?: {
+        score: number;
+        entityNovelty: number;
+        semanticNovelty: number;
+        accepted: boolean;
+    } | null;
+    candidates: IngestTraceCandidate[];
+}
+/** Find conflict candidates, merge slot-aware candidates, and filter out superseded. */
+export declare function findFilteredCandidates(deps: MemoryServiceDeps, userId: string, fact: FactInput, embedding: number[], claimSlot: ClaimSlotInput | null, supersededTargets: Set<string>): Promise<CandidateMemory[]>;
+/** Resolve AUDN decision (fast/deferred/full) and execute it. */
+export declare function resolveAndExecuteAudn(deps: MemoryServiceDeps, userId: string, fact: FactInput, embedding: number[], sourceSite: string, sourceUrl: string, episodeId: string, trustScore: number, claimSlot: ClaimSlotInput | null, logicalTimestamp: Date | undefined, filteredCandidates: CandidateMemory[], supersededTargets: Set<string>, workspace?: import('../db/repository-types.js').WorkspaceContext, traceContext?: AudnTraceContext): Promise<FactResult>;
+/**
+ * Execute an AUDN decision via the standard ingest seam.
+ *
+ * Exposed (renamed from the legacy private `executeDecision`) so that the
+ * TBC executor in `tbc-execution.ts` can route Affirm/Update/Retract/
+ * Supersede through the same mutation path AUDN uses today, keeping the
+ * fail-closed semantics in place.
+ */
+export declare function executeAudnDecision(deps: MemoryServiceDeps, decision: AUDNDecision, candidateIds: Set<string>, ctx: AudnFactContext): Promise<{
+    outcome: Outcome;
+    memoryId: string | null;
+}>;