@memory-river/core 0.2.0 → 0.2.2

package/dist/distill/concentrator-adapter.d.ts

@@ -7,6 +7,7 @@
  * 3. 雙軌並行提煉：短期前情提要 (大膠囊, health: 30) + 長期精確記憶 (小紙條)
  * 4. 完美回注與幽靈清理：注入 Context 頂端，並自動拔除斷片的 Tool Result
  */
+import { type ChildProcess } from 'node:child_process';
 import { ContextMessage } from '../types.js';
 import type { RawTranscriptEntry, TranscriptArchive } from '../transcript/transcript-archive.js';
 import type { SessionIdentity } from '../util/session-identity.js';
@@ -88,6 +89,21 @@ export declare function logProbeTextMismatchDetail(detail: ProbeTextMismatchDeta
 export declare function buildDualTrackPrompt(conversationLog: string, capsuleLanguage?: string): string;
 export declare function buildGeneralConversationPrompt(conversationLog: string, capsuleLanguage?: string): string;
 export declare function buildSimplePrompt(conversationLog: string, capsuleLanguage?: string): string;
+export type CodexReasoningEffort = 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+export interface CodexCliConfig {
+    model: string;
+    reasoningEffort: CodexReasoningEffort;
+    workdir: string;
+    timeoutMs: number;
+}
+type ExecFileCallback = (error: NodeJS.ErrnoException | null, stdout: string | Buffer, stderr: string | Buffer) => void;
+type ExecFileInvoker = (file: string, args: string[], options: {
+    cwd: string;
+    timeout: number;
+}, callback: ExecFileCallback) => Pick<ChildProcess, 'kill' | 'stdin'> | undefined;
+export declare function buildCodexExecArgs(prompt: string, config: CodexCliConfig): string[];
+export declare function parseCodexOutput(stdout: string): unknown;
+export declare function runCodexCli(prompt: string, config: CodexCliConfig, execFileImpl?: ExecFileInvoker): Promise<string>;
 export interface ConcentratorConfig {
     apiKey: string;
     model: string;
@@ -101,7 +117,11 @@ export interface ConcentratorConfig {
      */
     capsuleLanguage?: string;
     concentrationTarget?: number;
-    provider?: 'gemini' | 'deepseek';
+    provider?: 'codex' | 'gemini' | 'deepseek';
+    codexModel?: string;
+    codexReasoningEffort?: CodexReasoningEffort;
+    codexWorkdir?: string;
+    codexTimeoutMs?: number;
     maxTokens?: number;
     deepseekApiKey?: string;
     deepseekModel?: string;
@@ -142,7 +162,7 @@ export declare class ConcentratorAdapter implements LlmClient {
     };
     /**
      * Provider 輪替 fallback 核心方法
-     * 依序嘗試 gemini → deepseek，任一成功即返回
+     * 依序嘗試 codex → gemini → deepseek，任一成功即返回
      * Gemini 若連續 3 次 503，冷卻 90 秒內直接跳過
      */
     private callWithFallback;

package/dist/distill/concentrator-adapter.js

@@ -9,6 +9,8 @@
  */
 import * as path from 'node:path';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
+import { execFile } from 'node:child_process';
 import { CapsuleBridge } from '../pipeline/capsule-bridge.js';
 import { sharedLLMRateLimiter } from '../util/rate-limiter.js';
 const CONCRETE_FACT_NOTE_CATEGORIES = new Set([
@@ -1076,14 +1078,123 @@ function classifyConcentratorFailure(err) {
         return 'quota';
     return 'other';
 }
+const CODEX_FAILURE_BREAKER_THRESHOLD = 3;
+const CODEX_FAILURE_COOLDOWN_MS = 90_000;
 const GEMINI_503_BREAKER_THRESHOLD = 3;
 const GEMINI_503_COOLDOWN_MS = 90_000;
+let codexConsecutiveFailureCount = 0;
+let codexCooldownUntil = 0;
 let geminiConsecutive503Count = 0;
 let geminiCooldownUntil = 0;
 function isGemini503Error(err) {
     const message = String(err?.message ?? err ?? '').toLowerCase();
     return message.includes('gemini api error: 503');
 }
+export function buildCodexExecArgs(prompt, config) {
+    return [
+        'exec',
+        '-C', config.workdir,
+        '-c', `model=${config.model}`,
+        '-c', `model_reasoning_effort=${config.reasoningEffort}`,
+        prompt,
+    ];
+}
+function findBalancedJsonCandidates(text) {
+    const stack = [];
+    const candidates = [];
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (inString && ch === '\\') {
+            escaped = true;
+            continue;
+        }
+        if (ch === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        if (ch === '[' || ch === '{') {
+            stack.push({ opener: ch, start: i });
+            continue;
+        }
+        if (ch !== ']' && ch !== '}')
+            continue;
+        const expected = ch === ']' ? '[' : '{';
+        const top = stack[stack.length - 1];
+        if (!top || top.opener !== expected)
+            continue;
+        stack.pop();
+        candidates.push(text.slice(top.start, i + 1));
+    }
+    return candidates;
+}
+export function parseCodexOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        throw new Error('Codex CLI returned empty stdout');
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+    }
+    catch { }
+    const candidates = findBalancedJsonCandidates(stdout);
+    for (let i = candidates.length - 1; i >= 0; i--) {
+        try {
+            const parsed = JSON.parse(candidates[i]);
+            if (parsed && typeof parsed === 'object')
+                return parsed;
+        }
+        catch { }
+    }
+    throw new Error('Codex CLI stdout did not contain parseable JSON');
+}
+export function runCodexCli(prompt, config, execFileImpl = execFile) {
+    const args = buildCodexExecArgs(prompt, config);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timedOut = false;
+        let child;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child?.kill('SIGTERM');
+            reject(new Error(`Codex CLI timed out after ${config.timeoutMs}ms`));
+        }, config.timeoutMs);
+        const finish = (error, stdout, stderr) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (timedOut)
+                return;
+            if (error) {
+                const detail = String(stderr || error.message || error);
+                reject(new Error(`Codex CLI failed: ${detail}`));
+                return;
+            }
+            try {
+                resolve(JSON.stringify(parseCodexOutput(String(stdout))));
+            }
+            catch (parseError) {
+                reject(parseError);
+            }
+        };
+        child = execFileImpl('codex', args, {
+            cwd: config.workdir,
+            timeout: config.timeoutMs,
+        }, finish);
+        // execFile 不吃 stdio 選項,child 的 stdin 會是一個開著的 pipe,
+        // codex CLI 因此停在 "Reading additional input from stdin" 直到 timeout。
+        child?.stdin?.end();
+    });
+}
 function extractBalancedObjectForKey(text, key) {
     const keyIndex = text.indexOf(`"${key}"`);
     if (keyIndex === -1)
@@ -1298,6 +1409,10 @@ export class ConcentratorAdapter {
             capsuleLanguage: config.capsuleLanguage ?? '繁體中文',
             concentrationTarget: config.concentrationTarget ?? 0,
             provider: config.provider ?? 'gemini',
+            codexModel: config.codexModel ?? 'gpt-5.6-luna',
+            codexReasoningEffort: config.codexReasoningEffort ?? 'low',
+            codexWorkdir: config.codexWorkdir || os.homedir(),
+            codexTimeoutMs: config.codexTimeoutMs ?? 120000,
             maxTokens: config.maxTokens ?? 8192,
             deepseekApiKey: config.deepseekApiKey || '',
             deepseekModel: config.deepseekModel ?? 'deepseek-v4-flash',
@@ -1388,7 +1503,7 @@ export class ConcentratorAdapter {
         if (!needsCut) {
             return { messages, wasConcentrated: false, processedThroughIndex: 0 };
         }
-        if (!this.llm && !this.config.apiKey && !this.config.deepseekApiKey) {
+        if (!this.llm && this.config.provider !== 'codex' && !this.config.apiKey && !this.config.deepseekApiKey) {
             console.warn('[ConcentratorAdapter] Concentration skipped: no LLM API key configured; raw transcripts and recall remain available.');
             return { messages, wasConcentrated: false, processedThroughIndex: 0 };
         }
@@ -1683,7 +1798,7 @@ export class ConcentratorAdapter {
     }
     /**
      * Provider 輪替 fallback 核心方法
-     * 依序嘗試 gemini → deepseek，任一成功即返回
+     * 依序嘗試 codex → gemini → deepseek，任一成功即返回
      * Gemini 若連續 3 次 503，冷卻 90 秒內直接跳過
      */
     async callWithFallback(prompt, fnName = 'generate', fallbackPrompt, // concentrate 失敗時由呼叫端接 deterministic capsule；此處不處理
@@ -1691,22 +1806,44 @@ export class ConcentratorAdapter {
         if (this.llm) {
             return this.llm.generate(prompt, { purpose: fnName, maxTokens });
         }
-        const providers = [];
+        const providers = this.config.provider === 'codex'
+            ? ['codex', 'gemini', 'deepseek']
+            : ['gemini', 'deepseek'];
         const now = Date.now();
+        if (providers.includes('codex')) {
+            if (now < codexCooldownUntil) {
+                console.warn(`[${fnName}] codex skipped: circuit breaker cooling down for ${Math.ceil((codexCooldownUntil - now) / 1000)}s`);
+            }
+            else {
+                // codex has no API key; authentication belongs to the local CLI.
+            }
+        }
+        const eligibleProviders = providers.filter((provider) => provider !== 'codex' || now >= codexCooldownUntil);
         if (now < geminiCooldownUntil) {
             console.warn(`[${fnName}] gemini skipped: circuit breaker cooling down for ${Math.ceil((geminiCooldownUntil - now) / 1000)}s`);
         }
-        else {
-            providers.push('gemini');
-        }
-        providers.push('deepseek');
+        const orderedProviders = eligibleProviders.filter((provider) => provider !== 'gemini' || now >= geminiCooldownUntil);
         const attemptedProviders = [];
         const startedAt = Date.now();
         const shouldRecordMetric = fnName === 'concentrate';
         let lastError = null;
-        for (const provider of providers) {
+        for (const provider of orderedProviders) {
             attemptedProviders.push(provider);
             try {
+                if (provider === 'codex') {
+                    const result = await this.callProvider(provider, prompt, maxTokens);
+                    codexConsecutiveFailureCount = 0;
+                    await this.recordConcentratorAttemptMetric({
+                        metricContext,
+                        provider,
+                        outcome: 'success',
+                        attemptedProviders,
+                        inputTokens: metricContext?.inputTokens ?? estimatePromptTokens(prompt),
+                        outputTokens: estimatePromptTokens(result),
+                        durationMs: Date.now() - startedAt,
+                    }, shouldRecordMetric);
+                    return result;
+                }
                 if (provider === 'gemini') {
                     if (this.config.apiKey) {
                         const result = await this.callProvider(provider, prompt, maxTokens);
@@ -1745,7 +1882,14 @@ export class ConcentratorAdapter {
             }
             catch (err) {
                 console.warn(`[${fnName}] ${provider} failed; trying next provider:`, err);
-                if (provider === 'gemini') {
+                if (provider === 'codex') {
+                    codexConsecutiveFailureCount += 1;
+                    if (codexConsecutiveFailureCount >= CODEX_FAILURE_BREAKER_THRESHOLD) {
+                        codexCooldownUntil = Date.now() + CODEX_FAILURE_COOLDOWN_MS;
+                        console.warn(`[${fnName}] codex circuit breaker opened for ${CODEX_FAILURE_COOLDOWN_MS / 1000}s after ${codexConsecutiveFailureCount} consecutive failures`);
+                    }
+                }
+                else if (provider === 'gemini') {
                     if (isGemini503Error(err)) {
                         geminiConsecutive503Count += 1;
                         if (geminiConsecutive503Count >= GEMINI_503_BREAKER_THRESHOLD) {
@@ -1776,6 +1920,14 @@ export class ConcentratorAdapter {
         if (provider === 'gemini') {
             return callGeminiAPI(this.config.apiKey, this.config.model, prompt, maxTokens);
         }
+        if (provider === 'codex') {
+            return runCodexCli(prompt, {
+                model: this.config.codexModel,
+                reasoningEffort: this.config.codexReasoningEffort,
+                workdir: this.config.codexWorkdir,
+                timeoutMs: this.config.codexTimeoutMs,
+            });
+        }
         if (provider === 'deepseek') {
             return callDeepSeekAPI(this.config.deepseekApiKey, this.config.deepseekModel, prompt, maxTokens);
         }

package/dist/engine.js

@@ -87,7 +87,11 @@ export class MemoryRiverEngine {
                 apiKey: config.concentration?.geminiApiKey || config.embedding.apiKey || deps.geminiApiKey,
                 model: config.concentration?.model || 'gemini-2.5-flash-lite',
                 inboxPath: config.inboxPath,
-                provider: config.concentration?.provider || 'gemini',
+                provider: config.concentration?.provider || 'codex',
+                codexModel: config.concentration?.codexModel,
+                codexReasoningEffort: config.concentration?.codexReasoningEffort,
+                codexWorkdir: config.concentration?.codexWorkdir,
+                codexTimeoutMs: config.concentration?.codexTimeoutMs,
                 maxTokens: config.concentration?.maxTokens ?? 8192,
                 deepseekApiKey: config.concentration?.deepseekApiKey || deps.deepseekApiKey,
                 deepseekModel: config.concentration?.deepseekModel || 'deepseek-v4-flash',

package/dist/store/store-v4.d.ts

@@ -27,6 +27,7 @@ export declare function normalizeLanceUpdateValues(values: Record<string, unknow
 type DecayOptions = {
     coreCategories?: string[];
     coreImportanceThreshold?: number;
+    capsuleBypassCore?: boolean;
     skillCapsuleProtection?: boolean;
     dryRun?: boolean;
     deleteWith?: (id: string) => Promise<boolean>;

package/dist/store/store-v4.js

@@ -18,11 +18,26 @@ import { Schema, Field, Int64, Utf8, Bool, Float64 } from "apache-arrow";
 import { optimizeAuxTablesInConnection, recordAuxTableWrite, } from "./aux-table-maintenance.js";
 // 動態載入 jieba
 let jieba = null;
+let jiebaUnavailable = false;
 const loadJieba = async () => {
     if (jieba)
         return jieba;
+    if (jiebaUnavailable)
+        return null;
     const module = await import("nodejieba");
-    jieba = module.default ?? module;
+    const candidate = module.default ?? module;
+    // nodejieba 的 index.js 在原生 binding 缺失時仍能 import 成功,只有第一次真正
+    // 呼叫才丟。這裡先探一次,讓失敗落在 tokenizeChinese 的 catch 裡走降級,
+    // 而不是逃出去把每一次 store/update/ftsSearch 都打掛。
+    try {
+        candidate.cut("測");
+    }
+    catch (error) {
+        jiebaUnavailable = true;
+        console.warn("[MemoryStore] nodejieba unavailable, falling back to per-character Chinese tokenization:", error?.message ?? error);
+        throw error;
+    }
+    jieba = candidate;
     return jieba;
 };
 let lancedbImportPromise = null;
@@ -56,10 +71,13 @@ export class SchemaViolationError extends Error {
     }
 }
 // 預設健康度配置
+// coreImportanceThreshold 必須與 types.ts 的 DEFAULT_CLEANUP_CONFIG 一致。
+// 兩處曾經分別是 0.85 / 0.75,同一個「記憶要多重要才不被淘汰」的問題會因為
+// 呼叫入口不同而得到差一倍的答案(0.85→41% 受保護、0.75→76%)。改一邊要改兩邊。
 const DEFAULT_HEALTH_CONFIG = {
     initialScore: 100,
-    coreCategories: ["identity", "constraint", "business", "core_rule"],
-    coreImportanceThreshold: 0.85,
+    coreCategories: ["identity", "preference", "constraint", "business", "decision", "core_rule"],
+    coreImportanceThreshold: 0.75,
     skillDecayFactor: 0.25,
 };
 const STRING_UPDATE_FIELDS = new Set([
@@ -2678,6 +2696,7 @@ export class MemoryStore {
         let deferredDecay = 0, deferredDelete = 0;
         const effectiveCoreCategories = options.coreCategories ?? this.healthConfig.coreCategories;
         const effectiveCoreImportanceThreshold = options.coreImportanceThreshold ?? this.healthConfig.coreImportanceThreshold;
+        const capsuleBypassCore = options.capsuleBypassCore ?? true;
         const protectSkillCapsules = options.skillCapsuleProtection ?? true;
         const isDryRun = options.dryRun ?? false;
         const maxDelete = options.maxDelete === undefined ? Infinity : Math.max(0, Math.floor(options.maxDelete));
@@ -2706,14 +2725,16 @@ export class MemoryStore {
             const id = memoryRow.id;
             if (id.startsWith("init_"))
                 continue;
-            const isCore = effectiveCoreCategories.includes(memoryRow.category) ||
-                memoryRow.importance >= effectiveCoreImportanceThreshold;
+            const metaObj = this.parseMetadata(memoryRow.metadata);
+            // dynamic capsule 出生就是短命設計(health 30),不該因為 importance 高而被當成核心記憶保護
+            const isDynamicCapsule = metaObj?.type === 'dynamic_capsule';
+            const isCore = (!capsuleBypassCore || !isDynamicCapsule) && (effectiveCoreCategories.includes(memoryRow.category) ||
+                memoryRow.importance >= effectiveCoreImportanceThreshold);
             if (isCore) {
                 coreProtected++;
                 continue;
             }
             // 技能膠囊不參與灰塵清理(只響應用戶明確刪除)
-            const metaObj = this.parseMetadata(memoryRow.metadata);
             if (protectSkillCapsules && metaObj?.capsuleType === 'skill_capsule') {
                 continue;
             }

package/dist/types.d.ts

@@ -1,7 +1,3 @@
-/**
- * Unified Types - memory-river
- * Merged from v4/types.ts + context-river/concentrator.ts
- */
 export type MemoryCategory = "preference" | "fact" | "decision" | "entity" | "constraint" | "identity" | "business" | "knowledge" | "skill" | "other";
 export declare const MEMORY_CATEGORIES: readonly ["preference", "fact", "decision", "entity", "constraint", "identity", "business", "knowledge", "skill", "other"];
 export declare const PROTECTED_CATEGORIES: MemoryCategory[];
@@ -171,7 +167,7 @@ export interface TranscriptWatermarkRow {
     lineCount: number;
     updatedAt: number;
 }
-export type ConcentratorProvider = "gemini" | "deepseek" | "all_failed";
+export type ConcentratorProvider = "codex" | "gemini" | "deepseek" | "all_failed";
 export type ConcentratorStatOutcome = "success" | "partial" | "failure";
 export type ConcentratorFailureReason = "broken_json" | "timeout" | "quota" | "other";
 export interface ConcentratorStat {
@@ -284,8 +280,9 @@ export interface InboxWriteOptions {
  *    實際 embedder-v5.ts 使用 Ollama，不受此欄位影響。
  *
  * Concentration（濃縮）Provider 順序：
- *   - 預設：Gemini → DeepSeek
+ *   - 預設：Codex CLI → Gemini → DeepSeek
  *   - Gemini 若連續 3 次 503：冷卻 90 秒，期間直接跳過 Gemini
+ *   - Codex CLI 若連續 3 次失敗：冷卻 90 秒，期間直接跳過 Codex CLI
  *   - concentrate() 全失敗時仍由 ConcentratorAdapter 走 deterministic fallback capsule
  *
  * =============================================================================
@@ -351,8 +348,12 @@ export interface PluginConfig {
     };
     concentration?: {
         model?: string;
-        provider?: 'gemini' | 'deepseek';
+        provider?: 'codex' | 'gemini' | 'deepseek';
         geminiApiKey?: string;
+        codexModel?: string;
+        codexReasoningEffort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+        codexWorkdir?: string;
+        codexTimeoutMs?: number;
         maxTokens?: number;
         deepseekApiKey?: string;
         deepseekModel?: string;

package/dist/types.js

@@ -1,3 +1,8 @@
+/**
+ * Unified Types - memory-river
+ * Merged from v4/types.ts + context-river/concentrator.ts
+ */
+import * as os from 'node:os';
 export const MEMORY_CATEGORIES = [
     "preference",
     "fact",
@@ -55,8 +60,11 @@ export const DEFAULT_CONFIG = {
         decayPerRun: 5,
         decayIntervalMs: 24 * 60 * 60 * 1000,
         deleteThreshold: 0,
-        coreCategories: ["identity", "preference", "constraint", "business", "core_rule"],
-        coreImportanceThreshold: 0.8,
+        // 與上面 cleanupEngine 及 store-v4 的 DEFAULT_HEALTH_CONFIG 保持一致。
+        // 這三處曾經各寫各的(0.75 / 0.8 / 0.85,category 也是 6 / 5 / 4 類),
+        // 「記憶要多重要才不被淘汰」會因為呼叫入口不同而得到不同答案。改一處要改三處。
+        coreCategories: ["identity", "preference", "constraint", "business", "decision", "core_rule"],
+        coreImportanceThreshold: 0.75,
         skillDecayFactor: 0.25,
     },
     hooks: {
@@ -73,13 +81,13 @@ export const DEFAULT_CONFIG = {
     },
     concentration: {
         model: 'gemini-2.5-flash-lite',
-        /**
-         * @deprecated 此欄位已失效。實際 fallback 順序由 concentrator-adapter.ts 內定
-         *             （Gemini → DeepSeek），不受 config 影響。
-         *             保留欄位以避免破壞既有宿主設定，請勿依賴其值。
-         */
-        provider: 'gemini',
+        /** Provider chain starts with Codex when this is 'codex'; old values retain their legacy chain. */
+        provider: 'codex',
         geminiApiKey: "",
+        codexModel: 'gpt-5.6-luna',
+        codexReasoningEffort: 'low',
+        codexWorkdir: os.homedir(),
+        codexTimeoutMs: 120000,
         maxTokens: 8192,
         deepseekApiKey: "",
         deepseekModel: 'deepseek-v4-flash',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memory-river/core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Framework-neutral long-term memory engine for Node.js agents.",
   "private": false,
   "license": "Apache-2.0",