@remnic/core 1.1.30 → 9.3.515

package/src/compat/checks.test.ts

@@ -173,6 +173,39 @@ test("memory prompt section registration on api satisfies recall hook requiremen
   assert.equal(hookCheck.level, "ok");
 });
 
+test("service start detection ignores nested start properties", async () => {
+  const checks = await runFixture({
+    enginesNode: ">=22.12.0",
+    currentNodeVersion: "v22.12.0",
+    indexSource: [
+      "api.on('before_prompt_build', async () => {});",
+      "api.on('agent_end', async () => {});",
+      "api.registerService({ id: 'x', stop() {}, metadata: { start: false } });",
+      "registerCli(api, orchestrator);",
+    ].join("\n"),
+  });
+
+  const hookCheck = checkById(checks, "hook-registration-core");
+  assert.equal(hookCheck.level, "error");
+  assert.match(hookCheck.message, /startup wiring/);
+});
+
+test("service start detection accepts top-level start methods", async () => {
+  const checks = await runFixture({
+    enginesNode: ">=22.12.0",
+    currentNodeVersion: "v22.12.0",
+    indexSource: [
+      "api.on('before_prompt_build', async () => {});",
+      "api.on('agent_end', async () => {});",
+      "api.registerService({ id: 'x', stop() {}, metadata: { start: false }, start() {} });",
+      "registerCli(api, orchestrator);",
+    ].join("\n"),
+  });
+
+  const hookCheck = checkById(checks, "hook-registration-core");
+  assert.equal(hookCheck.level, "ok");
+});
+
 test("memory prompt section registration accepts casted api receivers", async () => {
   const checks = await runFixture({
     enginesNode: ">=22.12.0",

package/src/compat/checks.ts

@@ -3,10 +3,11 @@ import path from "node:path";
 import type { CompatCheckOptions, CompatCheckResult, CompatReport, CompatRunner } from "./types.js";
 import { compareVersions } from "../version-utils.js";
 import { launchProcess } from "../runtime/child-process.js";
-import { PLUGIN_ID, LEGACY_PLUGIN_ID } from "../plugin-id.js";
 
 const REQUIRED_HOOKS_LEGACY = ["before_agent_start", "agent_end"];
 const REQUIRED_HOOKS_NEW = ["before_prompt_build", "agent_end"];
+const OPENCLAW_REMNIC_PLUGIN_ID = "openclaw-remnic";
+const OPENCLAW_REMNIC_LEGACY_PLUGIN_ID = "openclaw-engram";
 
 function isSafeCommandToken(command: string): boolean {
   return /^[a-zA-Z0-9._-]+$/.test(command);
@@ -178,7 +179,66 @@ function parseHookRegistrations(source: string): Set<string> {
 }
 
 function hasServiceStartRegistration(source: string): boolean {
-  return /api\.registerService\s*\(\s*\{[\s\S]*?\bstart\s*(?::|\()/m.test(source);
+  let i = 0;
+  while (i < source.length) {
+    const callIndex = source.indexOf("api.registerService", i);
+    if (callIndex === -1) return false;
+    if (callIndex > 0 && /[a-zA-Z0-9_$\.]/.test(source[callIndex - 1])) {
+      i = callIndex + 1;
+      continue;
+    }
+
+    let cursor = callIndex + "api.registerService".length;
+    while (cursor < source.length && /\s/.test(source[cursor])) cursor += 1;
+    if (source[cursor] !== "(") {
+      i = callIndex + 1;
+      continue;
+    }
+
+    cursor += 1;
+    while (cursor < source.length && /\s/.test(source[cursor])) cursor += 1;
+    if (source[cursor] !== "{") {
+      i = callIndex + 1;
+      continue;
+    }
+
+    if (objectLiteralHasTopLevelStart(source, cursor)) return true;
+    i = cursor + 1;
+  }
+  return false;
+}
+
+function objectLiteralHasTopLevelStart(source: string, objectStart: number): boolean {
+  let depth = 0;
+  let i = objectStart;
+  while (i < source.length) {
+    const ch = source[i];
+    if (ch === "{") {
+      depth += 1;
+      i += 1;
+      continue;
+    }
+    if (ch === "}") {
+      depth -= 1;
+      if (depth === 0) return false;
+      i += 1;
+      continue;
+    }
+    if (depth === 1 && source.startsWith("start", i)) {
+      const before = source[i - 1];
+      const after = source[i + "start".length];
+      if (
+        (!before || !/[a-zA-Z0-9_$]/.test(before)) &&
+        (!after || !/[a-zA-Z0-9_$]/.test(after))
+      ) {
+        let cursor = i + "start".length;
+        while (cursor < source.length && /\s/.test(source[cursor])) cursor += 1;
+        if (source[cursor] === ":" || source[cursor] === "(") return true;
+      }
+    }
+    i += 1;
+  }
+  return false;
 }
 
 function hasCliRegistration(source: string): boolean {
@@ -523,7 +583,7 @@ export async function runCompatChecks(options: CompatCheckOptions): Promise<Comp
   if (pluginManifestPresent) {
     try {
       const plugin = JSON.parse(pluginRaw) as { id?: string; kind?: string };
-      const isValidId = plugin.id === PLUGIN_ID || plugin.id === LEGACY_PLUGIN_ID;
+      const isValidId = plugin.id === OPENCLAW_REMNIC_PLUGIN_ID || plugin.id === OPENCLAW_REMNIC_LEGACY_PLUGIN_ID;
       if (isValidId && plugin.kind === "memory") {
         checks.push({
           id: "plugin-manifest-shape",
@@ -537,7 +597,7 @@ export async function runCompatChecks(options: CompatCheckOptions): Promise<Comp
           title: "Plugin manifest ID and kind",
           level: "error",
           message: `Unexpected manifest values (id=${String(plugin.id)}, kind=${String(plugin.kind)})`,
-          remediation: `Set manifest id=${PLUGIN_ID} (or ${LEGACY_PLUGIN_ID} for the shim) and kind=memory.`,
+          remediation: `Set manifest id=${OPENCLAW_REMNIC_PLUGIN_ID} (or ${OPENCLAW_REMNIC_LEGACY_PLUGIN_ID} for the shim) and kind=memory.`,
         });
       }
     } catch {

package/src/compounding/engine.ts

@@ -45,7 +45,7 @@ type PromotionCandidate = {
   id: string;
   sourceType: "action-outcome" | "mistake-pattern" | "rubric" | "causal-pattern";
   subject: string;
-  category: "principle" | "rule";
+  category: "principle" | "rule" | "preference";
   content: string;
   score: number;
   rationale: string;
@@ -142,7 +142,7 @@ export interface CompoundingPromotionReport {
   promoted: Array<{
     id: string;
     candidateId: string;
-    category: "principle" | "rule";
+    category: "principle" | "rule" | "preference";
     content: string;
     confidence: number;
     tags: string[];

package/src/compounding/preference-consolidator.test.ts

@@ -0,0 +1,47 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { consolidatePreferences } from "./preference-consolidator.js";
+import type { MemoryFile } from "../types.js";
+
+function memory(content: string): MemoryFile {
+  return {
+    path: "/synthetic.md",
+    content,
+    frontmatter: {
+      id: `memory-${content}`,
+      category: "fact",
+      confidence: 0.8,
+      status: "active",
+      created: "2026-01-01T00:00:00.000Z",
+    },
+  } as MemoryFile;
+}
+
+test("consolidatePreferences preserves never-use facts as negative preferences", () => {
+  const result = consolidatePreferences([
+    memory("The user never uses Docker for deployments."),
+  ]);
+
+  assert.equal(result.preferences.length, 1);
+  assert.equal(
+    result.preferences[0]?.statement,
+    "The user would not prefer Docker for deployments",
+  );
+});
+
+test("consolidatePreferences preserves does-not-use facts as negative preferences", () => {
+  const result = consolidatePreferences([
+    memory("The user does not use React for dashboards."),
+  ]);
+
+  assert.equal(result.preferences.length, 1);
+  assert.equal(
+    result.preferences[0]?.statement,
+    "The user would not prefer React for dashboards",
+  );
+  assert.equal(
+    result.preferences[0]?.statement.includes("prefers to use"),
+    false,
+  );
+});

package/src/compounding/preference-consolidator.ts

@@ -46,6 +46,14 @@ const PREFERENCE_EXTRACTORS: Array<{
   pattern: RegExp;
   transform: (match: RegExpMatchArray, content: string) => string;
 }> = [
+  // "Avoids X" / negated use/work/code statements → negative preference
+  {
+    pattern: /(?:avoids?|dislikes?|hates?|does\s+not\s+like|doesn'?t\s+like|never\s+uses?|does\s+not\s+uses?|doesn'?t\s+uses?|does\s+not\s+use|doesn'?t\s+use|never\s+works?\s+(?:with|in)|does\s+not\s+works?\s+(?:with|in)|doesn'?t\s+works?\s+(?:with|in)|never\s+codes?\s+(?:in|with)|does\s+not\s+codes?\s+(?:in|with)|doesn'?t\s+codes?\s+(?:in|with)|refuses\s+to\s+(?:use|work\s+(?:with|in)|code\s+(?:in|with)))\s+(.+?)$/im,
+    transform: (match) => {
+      const subject = match[1].replace(/\.$/, "").trim();
+      return `The user would not prefer ${subject}`;
+    },
+  },
   // Direct preference statements
   {
     pattern: /(?:prefers?|enjoys?|likes?|loves?|favou?rs?)\s+(.+?)(?:\s+(?:for|when|in|over)\s+(.+?))?$/im,
@@ -64,14 +72,6 @@ const PREFERENCE_EXTRACTORS: Array<{
       return `The user prefers to use ${tool}${context}`;
     },
   },
-  // "Avoids X" / "Dislikes X" → negative preference
-  {
-    pattern: /(?:avoids?|dislikes?|hates?|doesn'?t\s+like|never\s+uses?)\s+(.+?)$/im,
-    transform: (match) => {
-      const subject = match[1].replace(/\.$/, "").trim();
-      return `The user would not prefer ${subject}`;
-    },
-  },
   // "Interested in X" → preference for X-related content
   {
     pattern: /(?:interested\s+in|passionate\s+about|focused\s+on|specializes?\s+in)\s+(.+?)$/im,

package/src/compression-optimizer.ts

@@ -50,10 +50,13 @@ function clamp(value: number, min: number, max: number): number {
 function parseRecallQuality(reason: string | undefined): "good" | "poor" | "unknown" {
   if (!reason) return "unknown";
   const text = reason.toLowerCase();
-  if (/(recall[_\s-]?good|quality[:=]\s*(good|high)|improv(ed|e)|resolved)/i.test(text)) {
+  if (/\bunresolved\b|\b(?:not|never|no|without)\s+(?:yet\s+)?resolved\b/.test(text)) {
+    return "poor";
+  }
+  if (/(recall[_\s-]?good|quality[:=]\s*(good|high)|\bimprov(?:e|ed|ing)\b|\bresolved\b)/.test(text)) {
     return "good";
   }
-  if (/(recall[_\s-]?poor|quality[:=]\s*(poor|low)|degrad(ed|e)|miss(ed|ing)|irrelevant)/i.test(text)) {
+  if (/(recall[_\s-]?poor|quality[:=]\s*(poor|low)|\bdegrad(?:e|ed|ing)\b|\bmiss(?:ed|ing)\b|\birrelevant\b)/.test(text)) {
     return "poor";
   }
   return "unknown";

package/src/config.test.ts

@@ -3,6 +3,24 @@ import test from "node:test";
 
 import { parseConfig } from "./config.js";
 
+test("parseConfig expands tilde paths for core storage directories", () => {
+  const previousHome = process.env.HOME;
+  process.env.HOME = "/Users/remnic-test";
+  try {
+    const result = parseConfig({
+      memoryDir: "~/memory",
+      workspaceDir: "~/workspace",
+      memoryExtensionsRoot: "~/extensions",
+    });
+    assert.equal(result.memoryDir, "/Users/remnic-test/memory");
+    assert.equal(result.workspaceDir, "/Users/remnic-test/workspace");
+    assert.equal(result.memoryExtensionsRoot, "/Users/remnic-test/extensions");
+  } finally {
+    if (previousHome === undefined) delete process.env.HOME;
+    else process.env.HOME = previousHome;
+  }
+});
+
 // ── PR #394 Bug 2: parseConfig must coerce string "false" for installExtension
 
 test('parseConfig codex.installExtension="false" (string) → false (boolean)', () => {
@@ -211,6 +229,20 @@ test("parseConfig localLlmTimeoutMs clamps invalid values to a positive timeout"
   assert.equal(parseConfig({ localLlmTimeoutMs: 0 }).localLlmTimeoutMs, 1);
   assert.equal(parseConfig({ localLlmTimeoutMs: Number.NaN }).localLlmTimeoutMs, 180_000);
 });
+
+test("parseConfig validates localLlmMaxContext as a usable context window", () => {
+  assert.equal(parseConfig({ localLlmMaxContext: 4096 }).localLlmMaxContext, 4096);
+  assert.equal(parseConfig({ localLlmMaxContext: "8192" }).localLlmMaxContext, 8192);
+  assert.equal(parseConfig({}).localLlmMaxContext, undefined);
+
+  for (const value of [0, -1, 128, 1023, 1.5, "1.5", "abc", Number.NaN, Infinity]) {
+    assert.throws(
+      () => parseConfig({ localLlmMaxContext: value }),
+      /localLlmMaxContext must be an integer greater than or equal to 1024/,
+      `invalid localLlmMaxContext ${String(value)} should throw`,
+    );
+  }
+});
 test("parseConfig extractionTelemetryPrefilterEnabled defaults on and accepts string false", () => {
   assert.equal(parseConfig({}).extractionTelemetryPrefilterEnabled, true);
   assert.equal(parseConfig({ extractionTelemetryPrefilterEnabled: "false" }).extractionTelemetryPrefilterEnabled, false);
@@ -312,9 +344,9 @@ test("parseConfig preserves custom entity schemas without code changes", () => {
 
 // ── Issue #518: direct-answer retrieval tier config ─────────────────────────
 
-test("parseConfig recallDirectAnswerEnabled defaults to true (slice 8a flip)", () => {
+test("parseConfig recallDirectAnswerEnabled defaults to false", () => {
   const result = parseConfig({});
-  assert.equal(result.recallDirectAnswerEnabled, true);
+  assert.equal(result.recallDirectAnswerEnabled, false);
 });
 
 test('parseConfig recallDirectAnswerEnabled coerces string "true" to boolean true', () => {

package/src/config.ts

@@ -28,6 +28,7 @@ import { log } from "./logger.js";
 import { cloneDefaultSessionObserverBands } from "./session-observer-bands.js";
 import { readEnvVar, resolveHomeDir } from "./runtime/env.js";
 import { normalizeEntitySchemas } from "./entity-schema.js";
+import { expandTildePath } from "./utils/path.js";
 // Finding 4 (#394): use the shared coerce helper instead of inlining the same
 // boolean-coercion logic that connectors/index.ts already exports. The helper
 // lives in connectors/coerce.ts (a tiny, dependency-free module) so neither
@@ -165,6 +166,46 @@ function parseIntegerAtLeast(
   return coerced;
 }
 
+function parseOptionalIntegerAtLeast(
+  value: unknown,
+  min: number,
+  keyName: string,
+): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  const coerced = coerceNumber(value);
+  if (
+    coerced === undefined ||
+    !Number.isFinite(coerced) ||
+    !Number.isInteger(coerced) ||
+    coerced < min
+  ) {
+    throw new Error(
+      `${keyName} must be an integer greater than or equal to ${min}; got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+function parsePortNumber(
+  value: unknown,
+  fallback: number,
+  keyName: string,
+): number {
+  if (value === undefined || value === null) return fallback;
+  const coerced = coerceNumber(value);
+  if (
+    coerced === undefined ||
+    !Number.isInteger(coerced) ||
+    coerced < 0 ||
+    coerced > 65535
+  ) {
+    throw new Error(
+      `${keyName} must be an integer from 0 to 65535; got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
 // Coerce common string/number representations of a boolean to a real boolean.
 // Returns `undefined` when the value cannot be interpreted, so callers can
 // fall back to their own default. Guards against the "string `false` is
@@ -234,6 +275,17 @@ function parseAgentAccessAuthToken(raw: unknown): import("./types.js").AgentAcce
   );
 }
 
+function parseAgentAccessPrincipal(raw: unknown): string | undefined {
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    return resolveEnvVars(raw);
+  }
+  return (
+    readEnvVar("OPENCLAW_REMNIC_ACCESS_PRINCIPAL")?.trim() ||
+    readEnvVar("OPENCLAW_ENGRAM_ACCESS_PRINCIPAL")?.trim() ||
+    undefined
+  );
+}
+
 export function resolveEnvVars(value: string): string {
   const resolved = value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, envVar: string) => {
     const envValue = readEnvVar(envVar);
@@ -957,7 +1009,7 @@ export function parseConfig(raw: unknown): PluginConfig {
 
   const memoryDir =
     typeof cfg.memoryDir === "string" && cfg.memoryDir.length > 0
-      ? cfg.memoryDir
+      ? expandTildePath(cfg.memoryDir)
       : DEFAULT_MEMORY_DIR;
   const rawIdentityInjectionMode = cfg.identityInjectionMode as string | undefined;
   const identityInjectionMode: IdentityInjectionMode =
@@ -1204,15 +1256,9 @@ export function parseConfig(raw: unknown): PluginConfig {
       typeof rawAgentAccessHttp?.host === "string" && rawAgentAccessHttp.host.trim().length > 0
         ? rawAgentAccessHttp.host.trim()
         : "127.0.0.1",
-    port:
-      typeof rawAgentAccessHttp?.port === "number"
-        ? Math.max(0, Math.floor(rawAgentAccessHttp.port))
-        : 4318,
+    port: parsePortNumber(rawAgentAccessHttp?.port, 4318, "agentAccessHttp.port"),
     [["auth", "Token"].join("")]: agentAccessAuthToken,
-    principal:
-      typeof rawAgentAccessHttp?.principal === "string" && rawAgentAccessHttp.principal.trim().length > 0
-        ? resolveEnvVars(rawAgentAccessHttp.principal)
-        : readEnvVar("OPENCLAW_ENGRAM_ACCESS_PRINCIPAL")?.trim() || undefined,
+    principal: parseAgentAccessPrincipal(rawAgentAccessHttp?.principal),
     maxBodyBytes:
       typeof rawAgentAccessHttp?.maxBodyBytes === "number"
         ? Math.max(1, Math.floor(rawAgentAccessHttp.maxBodyBytes))
@@ -1389,7 +1435,7 @@ export function parseConfig(raw: unknown): PluginConfig {
     ),
     workspaceDir:
       typeof cfg.workspaceDir === "string" && cfg.workspaceDir.length > 0
-        ? cfg.workspaceDir
+        ? expandTildePath(cfg.workspaceDir)
         : DEFAULT_WORKSPACE_DIR,
     captureMode,
     fileHygiene,
@@ -1461,13 +1507,11 @@ export function parseConfig(raw: unknown): PluginConfig {
     temporalSupersessionEnabled: cfg.temporalSupersessionEnabled !== false, // On by default
     temporalSupersessionIncludeInRecall:
       cfg.temporalSupersessionIncludeInRecall === true, // Off by default
-    // Direct-answer retrieval tier (issue #518).  Default on — the
-    // tier runs in observation mode: it annotates
-    // LastRecallSnapshot.tierExplain but never short-circuits the
-    // QMD path.  Operators can opt out with
-    // recallDirectAnswerEnabled=false.
+    // Direct-answer retrieval tier (issue #518).  Default off so the
+    // recall path keeps least-privileged behavior unless operators
+    // explicitly opt in.
     recallDirectAnswerEnabled:
-      coerceBool(cfg.recallDirectAnswerEnabled) ?? true,
+      coerceBool(cfg.recallDirectAnswerEnabled) ?? false,
     // Disclosure auto-escalation (issue #677 PR 4/4).  Default `manual`
     // so pre-#677 callers see unchanged behavior.  Reject anything
     // outside the allow-list rather than silently defaulting (CLAUDE.md
@@ -2152,7 +2196,7 @@ export function parseConfig(raw: unknown): PluginConfig {
     localLlmTimeoutMs:
       parseBoundedIntegerMs(cfg.localLlmTimeoutMs, 180_000, 1, 86_400_000),
     localLlmMaxContext:
-      typeof cfg.localLlmMaxContext === "number" ? cfg.localLlmMaxContext : undefined,
+      parseOptionalIntegerAtLeast(cfg.localLlmMaxContext, 1024, "localLlmMaxContext"),
     // Observability (disabled by default to avoid log spam)
     slowLogEnabled: cfg.slowLogEnabled === true,
     slowLogThresholdMs:
@@ -3376,7 +3420,7 @@ export function parseConfig(raw: unknown): PluginConfig {
     memoryExtensionsEnabled: cfg.memoryExtensionsEnabled !== false,
     memoryExtensionsRoot:
       typeof cfg.memoryExtensionsRoot === "string" && cfg.memoryExtensionsRoot.trim().length > 0
-        ? cfg.memoryExtensionsRoot.trim()
+        ? expandTildePath(cfg.memoryExtensionsRoot.trim())
         : "",
   };
 }

package/src/connectors/codex-materialize-runner.ts

@@ -81,6 +81,7 @@ export async function runCodexMaterialize(
 
   const namespace = resolveNamespace(options.namespace, cfg);
   const memoryDir = options.memoryDir ?? cfg.memoryDir;
+  const codexHome = options.codexHome ?? cfg.codex?.codexHome ?? undefined;
   if (!memoryDir) {
     log.warn(`[codex-materialize] skipped — no memoryDir available`);
     return null;
@@ -90,10 +91,10 @@ export async function runCodexMaterialize(
   if (options.memories) {
     memories = options.memories;
   } else {
-    if (!hasCodexMaterializeSentinel(options.codexHome)) {
+    if (!hasCodexMaterializeSentinel(codexHome)) {
       return materializeForNamespace(namespace, {
         memories: [],
-        codexHome: options.codexHome,
+        codexHome,
         maxSummaryTokens: cfg.codexMaterializeMaxSummaryTokens,
         rolloutRetentionDays: cfg.codexMaterializeRolloutRetentionDays,
         rolloutSummaries: options.rolloutSummaries,
@@ -114,7 +115,7 @@ export async function runCodexMaterialize(
   // ones for a feature that writes to `~/.codex/memories`.
   const result = materializeForNamespace(namespace, {
     memories,
-    codexHome: options.codexHome,
+    codexHome,
     maxSummaryTokens: cfg.codexMaterializeMaxSummaryTokens,
     rolloutRetentionDays: cfg.codexMaterializeRolloutRetentionDays,
     rolloutSummaries: options.rolloutSummaries,