@memorax/memorax-code 0.1.0

package/lib/memorax-code-backend/dist/memorax-config.js

@@ -0,0 +1,283 @@
+import { MEMORAX_DEFAULT_BASE_URL, MEMORAX_DEFAULT_MEMORY_OUTPUT_LANGUAGE, normalizeMemoraxBaseUrl, normalizeMemoraxMemoryOutputLanguage, } from "../../memorax-code-adapter-common/src/memorax-defaults.mjs";
+import { defaultMemoraxCodeHome, loadMemoraxCodeConfig, } from "./memorax-code-config.js";
+export { defaultMemoraxCodeHome, memoraxCodeConfigPath, loadMemoraxCodeConfig } from "./memorax-code-config.js";
+export { seedMissingMemoraxCodeConfig } from "./memorax-code-config.js";
+export { MEMORAX_DEFAULT_BASE_URL, MEMORAX_DEFAULT_MEMORY_OUTPUT_LANGUAGE };
+export const MEMORAX_PROVIDER_ID = "memory.memorax";
+export const MEMORAX_DEFAULT_MEMORY_TYPE_ORDER = ["core", "episodic", "semantic", "procedural", "unclassified"];
+export const MEMORAX_DEFAULT_STARTUP_TIMEOUT_MS = 3000;
+export const MEMORAX_MIN_STARTUP_TIMEOUT_MS = 100;
+export const MEMORAX_MAX_STARTUP_TIMEOUT_MS = 10_000;
+export const MEMORY_WRITEBACK_BUFFER_DEFAULT_MAX_TURNS = 8;
+export const MEMORY_WRITEBACK_BUFFER_DEFAULT_MAX_AGE_MS = 10 * 60 * 1000;
+export const MEMORY_WRITEBACK_BUFFER_DEFAULT_MAX_CHARS = 128_000;
+export const MEMORY_WRITEBACK_DEFAULT_MAX_MESSAGE_CHARS = 64_000;
+export const MEMORY_WRITEBACK_DEFAULT_CHUNK_MAX_CHARS = 8_000;
+export const MEMORY_WRITEBACK_DEFAULT_CHUNK_OVERLAP_RATIO = 0.05;
+export const MEMORY_CLI_DEFAULT_SESSION_ID = "memorax-cli";
+export const MEMORY_CLI_DEFAULT_MAX_MEMORY_CHARS = 2000;
+export function memoraxConfigFromEnv(env = process.env, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    const baseUrl = normalizeMemoraxBaseUrl(stringValue(env.MEMORAX_CODE_MEMORAX_ENDPOINT)
+        ?? config.memorax?.endpoint
+        ?? MEMORAX_DEFAULT_BASE_URL);
+    const apiKey = (stringValue(env.MEMORAX_CODE_MEMORAX_API_KEY) ?? config.memorax?.api_key ?? "").trim();
+    const userId = (stringValue(env.MEMORAX_CODE_MEMORAX_USER_ID) ?? config.memorax?.user_id ?? "").trim();
+    const outputLanguage = memoraxMemoryOutputLanguage(env, config);
+    if (!outputLanguage.ok)
+        return outputLanguage;
+    if (!apiKey)
+        return { ok: false, error: "MEMORAX_CODE_MEMORAX_API_KEY is required for memory.memorax" };
+    if (!userId)
+        return { ok: false, error: "MEMORAX_CODE_MEMORAX_USER_ID is required for memory.memorax" };
+    const searchConfig = memoraxSearchConfig(env, config);
+    const minScore = parseScore(env.MEMORAX_CODE_MEMORAX_MIN_SCORE ?? config.memory?.retrieval?.min_score);
+    return {
+        ok: true,
+        config: {
+            baseUrl,
+            apiKey,
+            userId,
+            memoryOutputLanguage: outputLanguage.value,
+            ...searchConfig,
+            ...(minScore === undefined ? {} : { minScore }),
+        },
+    };
+}
+function memoraxSearchConfig(env, config) {
+    const topK = clampInteger(env.MEMORAX_CODE_MEMORAX_TOP_K ?? config.memory?.retrieval?.top_k, 1, 100, config.memory?.retrieval?.top_k ?? 6);
+    return {
+        topK,
+        kDense: clampInteger(env.MEMORAX_CODE_MEMORAX_K_DENSE ?? config.memory?.retrieval?.k_dense, 0, 100, config.memory?.retrieval?.k_dense ?? topK),
+        kSparse: clampInteger(env.MEMORAX_CODE_MEMORAX_K_SPARSE ?? config.memory?.retrieval?.k_sparse, 0, 100, config.memory?.retrieval?.k_sparse ?? topK),
+        timeoutMs: clampInteger(env.MEMORAX_CODE_MEMORAX_TIMEOUT_MS ?? config.memorax?.timeout_ms, 1000, 120_000, config.memorax?.timeout_ms ?? 5000),
+        maxContextChars: clampInteger(env.MEMORAX_CODE_MEMORAX_MAX_CONTEXT_CHARS ?? config.memory?.retrieval?.max_context_chars, 256, 200_000, config.memory?.retrieval?.max_context_chars ?? 4000),
+        maxItemChars: clampInteger(env.MEMORAX_CODE_MEMORAX_MAX_ITEM_CHARS ?? config.memory?.retrieval?.max_item_chars, 64, 50_000, config.memory?.retrieval?.max_item_chars ?? 1000),
+        memoryTypeOrder: parseStringList(env.MEMORAX_CODE_MEMORAX_MEMORY_TYPE_ORDER ?? config.memory?.retrieval?.memory_type_order, config.memory?.retrieval?.memory_type_order ?? [...MEMORAX_DEFAULT_MEMORY_TYPE_ORDER]),
+        renderByMemoryType: parseBoolean(env.MEMORAX_CODE_MEMORAX_RENDER_BY_MEMORY_TYPE, config.memory?.retrieval?.render_by_memory_type ?? true),
+    };
+}
+export function startupRetrieveTimeoutMs(env, providerTimeoutMs, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    const startupCap = clampInteger(env.MEMORAX_CODE_MEMORAX_STARTUP_TIMEOUT_MS ?? config.memorax?.startup_timeout_ms, MEMORAX_MIN_STARTUP_TIMEOUT_MS, MEMORAX_MAX_STARTUP_TIMEOUT_MS, config.memorax?.startup_timeout_ms ?? MEMORAX_DEFAULT_STARTUP_TIMEOUT_MS);
+    return Math.min(providerTimeoutMs, startupCap);
+}
+export function memoraxWritebackEnabled(env = process.env) {
+    return env.MEMORAX_CODE_MEMORAX_WRITEBACK_ENABLED !== "false";
+}
+export function memoryRetrievalEnabled(env = process.env, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    return parseBoolean(env.MEMORAX_CODE_MEMORY_RETRIEVAL_ENABLED, config.memory?.retrieval?.enabled) === true;
+}
+export function memoryWritebackEnabled(env = process.env, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    return memoraxWritebackEnabled(env)
+        && memoryWritebackBufferConfig(env, config).maxTurns !== -1
+        && parseBoolean(env.MEMORAX_CODE_MEMORY_WRITEBACK_ENABLED, config.memory?.writeback?.enabled) === true;
+}
+export function memoryWritebackBufferEnabled(env = process.env, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    return parseBoolean(env.MEMORAX_CODE_MEMORY_WRITEBACK_BUFFER_ENABLED, config.memory?.writeback?.buffer_enabled ?? true) !== false;
+}
+export function memoryWritebackBufferConfig(env = process.env, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    return {
+        maxTurns: memoryWritebackAddInterval(env.MEMORAX_CODE_MEMORY_WRITEBACK_BUFFER_MAX_TURNS ?? config.memory?.writeback?.buffer_max_turns),
+        maxAgeMs: positiveInteger(env.MEMORAX_CODE_MEMORY_WRITEBACK_BUFFER_MAX_AGE_MS ?? config.memory?.writeback?.buffer_max_age_ms, config.memory?.writeback?.buffer_max_age_ms ?? MEMORY_WRITEBACK_BUFFER_DEFAULT_MAX_AGE_MS),
+        maxChars: positiveInteger(env.MEMORAX_CODE_MEMORY_WRITEBACK_BUFFER_MAX_CHARS ?? config.memory?.writeback?.buffer_max_chars, config.memory?.writeback?.buffer_max_chars ?? MEMORY_WRITEBACK_BUFFER_DEFAULT_MAX_CHARS),
+    };
+}
+function memoryWritebackAddInterval(value) {
+    if (String(value ?? "").trim() === "-1")
+        return -1;
+    return positiveInteger(value, MEMORY_WRITEBACK_BUFFER_DEFAULT_MAX_TURNS);
+}
+export function memoryWritebackMaxMessageChars(env = process.env, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    return positiveInteger(env.MEMORAX_CODE_MEMORY_WRITEBACK_MAX_MESSAGE_CHARS ?? config.memory?.writeback?.max_message_chars, config.memory?.writeback?.max_message_chars ?? MEMORY_WRITEBACK_DEFAULT_MAX_MESSAGE_CHARS);
+}
+export function memoryWritebackChunkEnabled(env = process.env, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    return parseBoolean(env.MEMORAX_CODE_MEMORY_WRITEBACK_CHUNK_ENABLED, config.memory?.writeback?.chunk_enabled ?? true) !== false;
+}
+export function memoryWritebackChunkConfig(env = process.env, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    return {
+        maxChars: positiveInteger(env.MEMORAX_CODE_MEMORY_WRITEBACK_CHUNK_MAX_CHARS ?? config.memory?.writeback?.chunk_max_chars, config.memory?.writeback?.chunk_max_chars ?? MEMORY_WRITEBACK_DEFAULT_CHUNK_MAX_CHARS),
+        overlapRatio: boundedRatio(env.MEMORAX_CODE_MEMORY_WRITEBACK_CHUNK_OVERLAP_RATIO ?? config.memory?.writeback?.chunk_overlap_ratio, config.memory?.writeback?.chunk_overlap_ratio ?? MEMORY_WRITEBACK_DEFAULT_CHUNK_OVERLAP_RATIO),
+    };
+}
+export function memoryCliAddEnabled(env = process.env, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    return parseBoolean(env.MEMORAX_CODE_MEMORY_CLI_ADD_ENABLED, config.memory?.cli?.add_enabled ?? true) === true
+        && memoraxWritebackEnabled(env);
+}
+export function memoryCliSessionId(args = [], env = process.env) {
+    return argValue(args, "--session-id")?.trim()
+        || env.MEMORAX_CODE_MEMORY_CLI_SESSION_ID?.trim()
+        || env.MEMORAX_CODE_MEMORAX_SESSION_ID?.trim()
+        || MEMORY_CLI_DEFAULT_SESSION_ID;
+}
+export function memoryCliMaxMemoryChars(env = process.env, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    return positiveInteger(env.MEMORAX_CODE_MEMORY_CLI_MAX_MEMORY_CHARS ?? config.memory?.cli?.max_memory_chars, config.memory?.cli?.max_memory_chars ?? MEMORY_CLI_DEFAULT_MAX_MEMORY_CHARS);
+}
+export function memoraxAddOptionsFromContext(context, env = process.env, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    const contentTypeValue = stringValue(context.contentType)
+        ?? stringValue(context.content_type)
+        ?? stringValue(env.MEMORAX_CODE_MEMORAX_ADD_CONTENT_TYPE)
+        ?? config.memory?.add?.content_type;
+    const modeValue = stringValue(context.mode)
+        ?? stringValue(env.MEMORAX_CODE_MEMORAX_ADD_MODE)
+        ?? config.memory?.add?.mode;
+    const contentTypeResult = parseAddContentType(contentTypeValue, "content_type");
+    if (!contentTypeResult.ok)
+        return contentTypeResult;
+    const modeResult = parseAddMode(modeValue, "mode");
+    if (!modeResult.ok)
+        return modeResult;
+    const contentType = contentTypeResult.value;
+    const mode = modeResult.value ?? (contentType ? "default" : undefined);
+    return {
+        ok: true,
+        options: {
+            ...(contentType ? { contentType } : {}),
+            ...(mode ? { mode } : {}),
+        },
+    };
+}
+export function memoryConfigStatus(env = process.env, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    const configResult = memoraxConfigFromEnv(env, config);
+    const baseConfig = configResult.ok ? configResult.config : undefined;
+    const addStatus = memoraxAddStatus(env, config);
+    const fallbackSearchConfig = {
+        ...memoraxSearchConfig(env, config),
+        minScore: parseScore(env.MEMORAX_CODE_MEMORAX_MIN_SCORE ?? config.memory?.retrieval?.min_score),
+    };
+    const searchConfig = baseConfig ?? fallbackSearchConfig;
+    return {
+        provider: MEMORAX_PROVIDER_ID,
+        ...(baseConfig ? { baseUrl: baseConfig.baseUrl, userId: baseConfig.userId } : {}),
+        configured: configResult.ok,
+        search: {
+            enabled: configResult.ok,
+            retrievalEnabled: memoryRetrievalEnabled(env, config),
+            topK: searchConfig.topK,
+            kDense: searchConfig.kDense,
+            kSparse: searchConfig.kSparse,
+            timeoutMs: searchConfig.timeoutMs,
+            startupTimeoutMs: startupRetrieveTimeoutMs(env, searchConfig.timeoutMs, config),
+            ...(searchConfig.minScore === undefined ? {} : { minScore: searchConfig.minScore }),
+            maxContextChars: searchConfig.maxContextChars,
+            maxItemChars: searchConfig.maxItemChars,
+            memoryTypeOrder: searchConfig.memoryTypeOrder,
+            renderByMemoryType: searchConfig.renderByMemoryType,
+        },
+        writeback: {
+            globalEnabled: memoraxWritebackEnabled(env),
+            writebackEnabled: memoryWritebackEnabled(env, config),
+            writebackBufferEnabled: memoryWritebackBufferEnabled(env, config),
+            writebackBuffer: memoryWritebackBufferConfig(env, config),
+            writebackMaxMessageChars: memoryWritebackMaxMessageChars(env, config),
+            writebackChunkEnabled: memoryWritebackChunkEnabled(env, config),
+            writebackChunk: memoryWritebackChunkConfig(env, config),
+        },
+        add: addStatus,
+        cli: {
+            addEnabled: memoryCliAddEnabled(env, config),
+            sessionId: memoryCliSessionId([], env),
+            maxMemoryChars: memoryCliMaxMemoryChars(env, config),
+        },
+        ...(configResult.ok ? {} : { error: configResult.error }),
+    };
+}
+function configForEnv(env, fileConfig) {
+    return fileConfig ?? loadMemoraxCodeConfig(defaultMemoraxCodeHome(env));
+}
+function memoraxAddStatus(env, fileConfig) {
+    const config = configForEnv(env, fileConfig);
+    const contentTypeResult = parseAddContentType(stringValue(env.MEMORAX_CODE_MEMORAX_ADD_CONTENT_TYPE) ?? config.memory?.add?.content_type, "content_type");
+    const modeResult = parseAddMode(stringValue(env.MEMORAX_CODE_MEMORAX_ADD_MODE) ?? config.memory?.add?.mode, "mode");
+    const outputLanguage = memoraxMemoryOutputLanguage(env, config);
+    return {
+        ...(contentTypeResult.ok && contentTypeResult.value ? { contentType: contentTypeResult.value } : {}),
+        ...(modeResult.ok && modeResult.value ? { mode: modeResult.value } : {}),
+        ...(outputLanguage.ok ? { outputLanguage: outputLanguage.value } : {}),
+    };
+}
+function memoraxMemoryOutputLanguage(env, config) {
+    const raw = stringValue(env.MEMORAX_CODE_MEMORY_OUTPUT_LANGUAGE)
+        ?? stringValue(config.memory?.add?.output_language)
+        ?? MEMORAX_DEFAULT_MEMORY_OUTPUT_LANGUAGE;
+    const value = normalizeMemoraxMemoryOutputLanguage(raw);
+    return value
+        ? { ok: true, value }
+        : { ok: false, error: "memory output language must be zh or en" };
+}
+function parseAddContentType(value, label) {
+    if (!value)
+        return { ok: true };
+    if (value === "dialogue" || value === "code")
+        return { ok: true, value };
+    return { ok: false, error: `${label} must be dialogue or code` };
+}
+function parseAddMode(value, label) {
+    if (!value)
+        return { ok: true };
+    if (value === "default" || value === "raw" || value === "pre_summarized")
+        return { ok: true, value };
+    return { ok: false, error: `${label} must be default, raw, or pre_summarized` };
+}
+export function parseBoolean(value, fallback) {
+    if (value === undefined || value === null || value === "")
+        return fallback;
+    if (typeof value === "boolean")
+        return value;
+    const normalized = String(value).trim().toLowerCase();
+    if (["1", "true", "yes", "y", "on"].includes(normalized))
+        return true;
+    if (["0", "false", "no", "n", "off"].includes(normalized))
+        return false;
+    return fallback;
+}
+export function positiveInteger(value, fallback) {
+    if (value === undefined || value === null || value === "")
+        return fallback;
+    const parsed = typeof value === "number" ? value : Number.parseInt(String(value).trim(), 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+export function boundedRatio(value, fallback) {
+    if (value === undefined || value === null || value === "")
+        return fallback;
+    const parsed = typeof value === "number" ? value : Number.parseFloat(String(value).trim());
+    return Number.isFinite(parsed) && parsed >= 0 && parsed < 1 ? parsed : fallback;
+}
+export function clampInteger(value, min, max, fallback = min) {
+    const number = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(number))
+        return fallback;
+    return Math.max(min, Math.min(max, Math.trunc(number)));
+}
+export function parseScore(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const number = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(number) && number >= 0 && number <= 1 ? number : undefined;
+}
+export function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+export function parseStringList(value, fallback) {
+    if (Array.isArray(value))
+        return value.map((item) => String(item).trim()).filter(Boolean);
+    if (typeof value !== "string" || !value.trim())
+        return [...fallback];
+    const items = value.split(",").map((item) => item.trim()).filter(Boolean);
+    return items.length > 0 ? items : [...fallback];
+}
+function argValue(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}

package/lib/memorax-code-backend/dist/memorax-http.js

@@ -0,0 +1,142 @@
+import { isRecord } from "./utils.js";
+export async function postMemoraxJson(config, path, payload, fetchImpl) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+    try {
+        const response = await fetchImpl(`${config.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Token ${config.apiKey}`,
+            },
+            body: JSON.stringify(payload),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
+            await response.arrayBuffer().catch(() => undefined);
+            throw createMemoraxRequestError(`MemoraX HTTP ${response.status}`, "http", {
+                status: response.status,
+                retryAfterMs,
+            });
+        }
+        const raw = await response.json().catch(() => null);
+        validateMemoraxEnvelope(raw);
+        return raw;
+    }
+    catch (error) {
+        throw normalizeMemoraxRequestError(error, controller.signal.aborted);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export async function getMemoraxJson(config, path, fetchImpl) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.timeoutMs);
+    try {
+        const response = await fetchImpl(`${config.baseUrl}${path}`, {
+            method: "GET",
+            headers: {
+                Authorization: `Token ${config.apiKey}`,
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
+            await response.arrayBuffer().catch(() => undefined);
+            throw createMemoraxRequestError(`MemoraX HTTP ${response.status}`, "http", {
+                status: response.status,
+                retryAfterMs,
+            });
+        }
+        return await response.json().catch(() => null);
+    }
+    catch (error) {
+        throw normalizeMemoraxRequestError(error, controller.signal.aborted);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export function memoraxInvocationFailure(error) {
+    const requestError = error instanceof Error ? error : undefined;
+    return {
+        ok: false,
+        error: formatMemoraxError(error),
+        ...(requestError?.memoraxErrorKind ? { errorKind: requestError.memoraxErrorKind } : {}),
+        ...(Number.isInteger(requestError?.status) ? { httpStatus: requestError?.status } : {}),
+        ...(Number.isFinite(requestError?.retryAfterMs) ? { retryAfterMs: requestError?.retryAfterMs } : {}),
+    };
+}
+function createMemoraxRequestError(message, kind, fields = {}) {
+    const error = new Error(message);
+    error.memoraxErrorKind = kind;
+    if (fields.status !== undefined)
+        error.status = fields.status;
+    if (fields.retryAfterMs !== undefined)
+        error.retryAfterMs = fields.retryAfterMs;
+    return error;
+}
+function normalizeMemoraxRequestError(error, timedOut) {
+    if (isMemoraxRequestError(error))
+        return error;
+    const kind = timedOut || (error instanceof Error && error.name === "AbortError")
+        ? "timeout"
+        : "transport";
+    return createMemoraxRequestError(formatMemoraxError(error), kind);
+}
+function isMemoraxRequestError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const kind = error.memoraxErrorKind;
+    return kind === "http"
+        || kind === "timeout"
+        || kind === "transport"
+        || kind === "response";
+}
+function formatMemoraxError(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+function parseRetryAfterMs(value, now = Date.now()) {
+    const text = value?.trim();
+    if (!text)
+        return undefined;
+    if (/^\d+$/.test(text))
+        return Number.parseInt(text, 10) * 1000;
+    const at = Date.parse(text);
+    if (!Number.isFinite(at))
+        return undefined;
+    return Math.max(0, at - now);
+}
+function validateMemoraxEnvelope(raw) {
+    if (!isRecord(raw))
+        return;
+    if (raw.success === false) {
+        throw createMemoraxRequestError(memoraxEnvelopeErrorMessage(raw), "response");
+    }
+    const data = isRecord(raw.data) ? raw.data : undefined;
+    const status = typeof data?.status === "string" ? data.status.trim().toLowerCase() : "";
+    if (["failed", "error", "cancelled", "canceled"].includes(status)) {
+        throw createMemoraxRequestError(memoraxEnvelopeErrorMessage(raw, `MemoraX task ${status}`), "response");
+    }
+}
+function memoraxEnvelopeErrorMessage(raw, fallback = "MemoraX request failed") {
+    const error = raw.error;
+    if (typeof error === "string" && error.trim())
+        return error.trim();
+    if (isRecord(error)) {
+        for (const key of ["message", "detail", "error"]) {
+            const value = error[key];
+            if (typeof value === "string" && value.trim())
+                return value.trim();
+        }
+    }
+    const data = isRecord(raw.data) ? raw.data : undefined;
+    const message = data?.message ?? data?.error;
+    if (typeof message === "string" && message.trim())
+        return message.trim();
+    return fallback;
+}