agenr 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [0.8.4]
+
+### Added
+- feat(openclaw-plugin): project scoping via config.project in openclaw.json; all session-start recall and store calls are scoped to the configured project when set (issue #71)
+- feat(openclaw-plugin): optional subject field in agenr_store schema; agents can now pass an explicit subject per entry rather than always relying on inference (issue #86)
+- feat(openclaw-plugin): platform normalization and source_file format warnings in runStoreTool; platform is inferred from source when missing, invalid values are warned and dropped, freeform source strings trigger a format hint (issue #145)
+
+### Fixed
+- fix(recall): cap final recall scores at 1.0 after FTS bonus; Math.min(1.0) applied in scoreEntryWithBreakdown (issue #64)
+- fix(mcp): correct misleading retire tool message; retired entries are hidden from all recall paths (issue #143)
+- fix(mcp): inferSubject now splits on punctuation followed by whitespace only, preventing truncation on file path periods (e.g. .ts, .js)
+- fix(openclaw-plugin): subject inference in runStoreTool processedEntries now uses the same safe regex as inferSubject
+
+### Changed
+- chore(openclaw-plugin): remove openclaw.plugin.json version field; package.json is now the single source of truth (issue #91)
+- chore(openclaw-plugin): remove formatRecallAsSummary dead code; writeAgenrMd was already removed, this cleans up the last orphaned export (issue #77)
+
+## [0.8.3]
+
+### Fixed
+- setup: custom model aliases (gpt-4.1-nano, gpt-4.1-mini) now appear in
+  the model picker when using openai-api-key auth (issue #136)
+- setup: revert hint null-normalization regression (details?.name ?? undefined)
+- setup: warn user when empty credential is entered during key rotation
+- setup: note that updated credential is saved but not re-validated
+- setup: openai-api-key now prioritizes gpt-4.1-nano, gpt-4.1-mini, and
+  gpt-5-nano in preferred model selection, and adds gpt-5-nano alias
+  resolution for OpenAI model lookup
+- setup: reconfigure now offers to update stored API key even when existing
+  credential is valid (issue #13)
+- embeddings: EmbeddingCache is now bounded with LRU eviction (default
+  max 5000 entries) to prevent unbounded heap growth during large ingests
+  (issue #57)
+- embeddings: EmbeddingCache constructor throws RangeError for maxSize < 1
+
 ## [0.8.2] - 2026-02-22
 
 ### Added

package/README.md

@@ -12,7 +12,7 @@ One local database. Your memory stays on your machine.
 
 AGENR uses embeddings to make your memory searchable. The best setup we've found: an **OpenAI API key** with `text-embedding-3-small`. Embeddings cost fractions of a penny per operation - a full ingestion of 100+ session transcripts runs about $0.10 total.
 
-AGENR also supports **OpenAI Pro subscriptions** and **Anthropic Claude subscriptions** (no API key needed) for the LLM extraction step. But for the best balance of speed, accuracy, and cost, we recommend `gpt-4o-mini` with an API key. `agenr setup` walks you through all of this.
+AGENR also supports **OpenAI Pro subscriptions** and **Anthropic Claude subscriptions** (no API key needed) for the LLM extraction step. But for the best balance of speed, accuracy, and cost, we recommend `gpt-4.1-nano` with an API key. `agenr setup` walks you through all of this.
 
 ```bash
 export OPENAI_API_KEY=sk-...  # for embeddings + extraction

package/dist/cli-main.js

@@ -43,7 +43,8 @@ var MODEL_ALIASES = {
     "gpt-codex": "gpt-5.2-codex",
     "gpt-4.1-nano": "openai/gpt-4.1-nano",
     "gpt-4.1-mini": "openai/gpt-4.1-mini",
-    "gpt-4.1": "openai/gpt-4.1"
+    "gpt-4.1": "openai/gpt-4.1",
+    "gpt-5-nano": "openai/gpt-5-nano"
   },
   "openai-codex": {
     codex: "gpt-5.3-codex",
@@ -138,7 +139,7 @@ var AUTH_METHOD_DEFINITIONS = [
     provider: "openai",
     title: "OpenAI -- API key",
     setupDescription: "Standard API key from platform.openai.com. Pay per token.",
-    preferredModels: ["gpt-4o", "openai/gpt-4.1-nano", "gpt-4o-mini"]
+    preferredModels: ["gpt-4.1-nano", "gpt-4.1-mini", "gpt-5-nano"]
   }
 ];
 var AUTH_METHOD_SET = new Set(AUTH_METHOD_DEFINITIONS.map((item) => item.id));
@@ -3847,7 +3848,8 @@ function scoreEntryWithBreakdown(entry, vectorSim, ftsMatch, now, freshnessNow =
   const memoryStrength = Math.min(Math.max(imp, spacedRecallBase) * fresh, 1);
   const todoPenalty = entry.type === "todo" ? todoStaleness(entry, now) : 1;
   const contradictionPenalty = entry.contradictions >= 2 ? 0.8 : 1;
-  const score = sim * (0.3 + 0.7 * rec) * memoryStrength * todoPenalty * contradictionPenalty + fts;
+  const rawScore = sim * (0.3 + 0.7 * rec) * memoryStrength * todoPenalty * contradictionPenalty + fts;
+  const score = Math.min(1, rawScore);
   return {
     score,
     scores: {
@@ -3857,6 +3859,7 @@ function scoreEntryWithBreakdown(entry, vectorSim, ftsMatch, now, freshnessNow =
       recall: recallBase,
       freshness: fresh,
       todoPenalty,
+      // FTS bonus component before the final score is capped at 1.0.
       fts,
       spacing: spacingFactor
     }
@@ -4533,12 +4536,75 @@ async function retireEntries(opts) {
 
 // src/embeddings/cache.ts
 var EmbeddingCache = class {
-  embeddings = /* @__PURE__ */ new Map();
+  maxSize;
+  map = /* @__PURE__ */ new Map();
+  head = null;
+  // most recently used key
+  tail = null;
+  // least recently used key
+  constructor(maxSize = 5e3) {
+    if (!(maxSize >= 1)) {
+      throw new RangeError(`EmbeddingCache maxSize must be at least 1. Received: ${String(maxSize)}.`);
+    }
+    this.maxSize = maxSize;
+  }
   get(text2) {
-    return this.embeddings.get(text2);
+    const node = this.map.get(text2);
+    if (!node) return void 0;
+    this.moveToHead(text2, node);
+    return node.value;
   }
   set(text2, embedding) {
-    this.embeddings.set(text2, embedding);
+    if (this.map.has(text2)) {
+      const node2 = this.map.get(text2);
+      node2.value = embedding;
+      this.moveToHead(text2, node2);
+      return;
+    }
+    if (this.map.size >= this.maxSize) {
+      this.evictTail();
+    }
+    const node = { value: embedding, prev: null, next: this.head };
+    this.map.set(text2, node);
+    if (this.head !== null) {
+      this.map.get(this.head).prev = text2;
+    }
+    this.head = text2;
+    if (this.tail === null) {
+      this.tail = text2;
+    }
+  }
+  get size() {
+    return this.map.size;
+  }
+  moveToHead(key, node) {
+    if (this.head === key) return;
+    if (node.prev !== null) {
+      this.map.get(node.prev).next = node.next;
+    }
+    if (node.next !== null) {
+      this.map.get(node.next).prev = node.prev;
+    } else {
+      this.tail = node.prev;
+    }
+    node.prev = null;
+    node.next = this.head;
+    if (this.head !== null) {
+      this.map.get(this.head).prev = key;
+    }
+    this.head = key;
+  }
+  evictTail() {
+    if (this.tail === null) return;
+    const tailKey = this.tail;
+    const tailNode = this.map.get(tailKey);
+    this.tail = tailNode.prev;
+    if (this.tail !== null) {
+      this.map.get(this.tail).next = null;
+    } else {
+      this.head = null;
+    }
+    this.map.delete(tailKey);
   }
 };
 
@@ -15285,10 +15351,15 @@ function inferSubject(content) {
   if (!trimmed) {
     return "memory";
   }
-  const firstClause = trimmed.split(/[.!?]/)[0] ?? trimmed;
-  const words = firstClause.split(/\s+/).filter((word) => word.length > 0).slice(0, 6);
-  const candidate = words.join(" ");
-  return candidate.slice(0, 80) || "memory";
+  const firstClause = trimmed.split(/[.!?:;]\s/)[0].trim();
+  if (!firstClause) {
+    return "memory";
+  }
+  if (firstClause.length <= 80) {
+    return firstClause;
+  }
+  const cut = firstClause.lastIndexOf(" ", 80);
+  return cut > 0 ? firstClause.slice(0, cut) : firstClause.slice(0, 80);
 }
 function parseStoreEntries(rawEntries) {
   if (!Array.isArray(rawEntries)) {
@@ -15753,7 +15824,7 @@ function createMcpServer(options = {}, deps = {}) {
     if (retired.count === 0) {
       throw new RpcError(JSON_RPC_INVALID_PARAMS, `No active entry found with id: ${entryId}`);
     }
-    const messageBase = `Retired: ${subject} (type: ${type}). Entry is hidden from session-start recall but can still be found with explicit queries.`;
+    const messageBase = `Retired: ${subject} (type: ${type}). Entry is hidden from all recall (session-start and explicit queries).`;
     const text2 = persist ? `${messageBase} Retirement will survive database re-ingest.` : messageBase;
     return text2;
   }
@@ -18131,7 +18202,14 @@ function promptToEnterCredential(auth) {
 function modelChoicesForAuth(auth, provider) {
   const definition = getAuthMethodDefinition(auth);
   const allModels = getModels(provider).map((model) => model.id);
-  const preferred = definition.preferredModels.filter((modelId) => allModels.includes(modelId));
+  const preferred = definition.preferredModels.filter((modelId) => {
+    try {
+      resolveModel(provider, modelId);
+      return true;
+    } catch {
+      return false;
+    }
+  });
   const fallback = allModels.filter((modelId) => !preferred.includes(modelId));
   if (provider === "openai") {
     const prioritizedFallback = fallback.filter(
@@ -18194,9 +18272,9 @@ async function runSetup(env = process.env) {
     storedCredentials: working.credentials,
     env
   });
+  const credentialKey = credentialKeyForAuth(auth);
   if (!probe.available) {
     clack11.log.warn(probe.guidance);
-    const credentialKey = credentialKeyForAuth(auth);
     if (credentialKey) {
       const shouldEnterNow = await clack11.confirm({
         message: "Enter the credential now?",
@@ -18225,6 +18303,36 @@ async function runSetup(env = process.env) {
         }
       }
     }
+  } else if (existing && credentialKey) {
+    const updateKey = await clack11.confirm({
+      message: "Update stored credential?",
+      initialValue: false
+    });
+    if (clack11.isCancel(updateKey)) {
+      clack11.cancel("Setup cancelled.");
+      return;
+    }
+    if (updateKey) {
+      const entered = await clack11.password({
+        message: promptToEnterCredential(auth)
+      });
+      if (clack11.isCancel(entered)) {
+        clack11.cancel("Setup cancelled.");
+        return;
+      }
+      const normalized = entered.trim();
+      if (normalized) {
+        working = setStoredCredential(working, credentialKey, normalized);
+        probe = probeCredentials({
+          auth,
+          storedCredentials: working.credentials,
+          env
+        });
+        clack11.log.info("Credential updated.");
+      } else {
+        clack11.log.warn("Credential not updated - empty input.");
+      }
+    }
   }
   const modelChoices = modelChoicesForAuth(auth, provider);
   if (modelChoices.length === 0) {

package/dist/openclaw-plugin/index.js

@@ -30,7 +30,7 @@ function buildSpawnArgs(agenrPath) {
   }
   return { cmd: agenrPath, args: [] };
 }
-async function runRecall(agenrPath, budget) {
+async function runRecall(agenrPath, budget, project) {
   return await new Promise((resolve) => {
     let stdout = "";
     let settled = false;
@@ -42,11 +42,13 @@ async function runRecall(agenrPath, budget) {
       settled = true;
       resolve(value);
     }
-    const child = spawn(
-      spawnArgs.cmd,
-      [...spawnArgs.args, "recall", "--context", "session-start", "--budget", String(budget), "--json"],
-      { stdio: ["ignore", "pipe", "ignore"] }
-    );
+    const args = ["recall", "--context", "session-start", "--budget", String(budget), "--json"];
+    if (project) {
+      args.push("--project", project);
+    }
+    const child = spawn(spawnArgs.cmd, [...spawnArgs.args, ...args], {
+      stdio: ["ignore", "pipe", "ignore"]
+    });
     const timer = setTimeout(() => {
       child.kill("SIGTERM");
       finish(null);
@@ -245,6 +247,9 @@ import { tmpdir } from "os";
 import { join } from "path";
 var TOOL_TIMEOUT_MS = 1e4;
 var EXTRACT_TIMEOUT_MS = 6e4;
+var KNOWN_PLATFORMS = /* @__PURE__ */ new Set(["openclaw", "codex", "claude-code", "plaud"]);
+var RECOMMENDED_SOURCE_PREFIXES = ["mcp:", "file:", "cli:", "session:", "conversation"];
+var SOURCE_FORMAT_WARNING = "agenr_store: source_file does not follow recommended format (mcp:, file:, cli:, session:, conversation). Storing as-is.";
 function asString(value) {
   if (typeof value !== "string") {
     return void 0;
@@ -264,6 +269,54 @@ function asNumber(value) {
   }
   return void 0;
 }
+function resolveWarn(pluginConfig) {
+  const logger = pluginConfig?.logger;
+  if (logger && typeof logger === "object") {
+    const warn = logger.warn;
+    if (typeof warn === "function") {
+      return (message) => {
+        warn(message);
+      };
+    }
+  }
+  return (message) => {
+    console.warn(message);
+  };
+}
+function sourceStringFromEntry(entry) {
+  if (typeof entry.source === "string") {
+    return entry.source;
+  }
+  if (entry.source && typeof entry.source === "object") {
+    const sourceFile = asString(entry.source.file);
+    if (sourceFile) {
+      return sourceFile;
+    }
+  }
+  return void 0;
+}
+function inferPlatformFromEntries(entries) {
+  for (const entry of entries) {
+    const source = sourceStringFromEntry(entry);
+    if (!source) {
+      continue;
+    }
+    const normalizedSource = source.toLowerCase();
+    if (normalizedSource.includes("codex")) {
+      return "codex";
+    }
+    if (normalizedSource.includes("claude")) {
+      return "claude-code";
+    }
+    if (normalizedSource.includes("openclaw")) {
+      return "openclaw";
+    }
+    if (normalizedSource.includes("plaud")) {
+      return "plaud";
+    }
+  }
+  return void 0;
+}
 async function runAgenrCommand(agenrPath, args, stdinPayload, timeoutMs = TOOL_TIMEOUT_MS) {
   return await new Promise((resolve) => {
     const resolvedAgenrPath = agenrPath.trim() || resolveAgenrPath();
@@ -306,7 +359,7 @@ async function runAgenrCommand(agenrPath, args, stdinPayload, timeoutMs = TOOL_T
     child.stdin.end();
   });
 }
-async function runRecallTool(agenrPath, params) {
+async function runRecallTool(agenrPath, params, defaultProject) {
   const args = ["recall", "--json"];
   const query = asString(params.query);
   const context = asString(params.context);
@@ -315,7 +368,7 @@ async function runRecallTool(agenrPath, params) {
   const since = asString(params.since);
   const until = asString(params.until);
   const platform = asString(params.platform);
-  const project = asString(params.project);
+  const project = asString(params.project) || defaultProject;
   if (query) {
     args.push(query);
   }
@@ -377,10 +430,44 @@ async function runRecallTool(agenrPath, params) {
     };
   }
 }
-async function runStoreTool(agenrPath, params, pluginConfig) {
+async function runStoreTool(agenrPath, params, pluginConfig, defaultProject) {
   const entries = Array.isArray(params.entries) ? params.entries : [];
-  const platform = asString(params.platform);
-  const project = asString(params.project);
+  const project = asString(params.project) || defaultProject;
+  const warn = resolveWarn(pluginConfig);
+  const processedEntries = entries.map((e) => {
+    const entry = e && typeof e === "object" ? e : {};
+    if (!entry.subject && typeof entry.content === "string") {
+      entry.subject = entry.content.slice(0, 60).replace(/[.!?:;]\s[\s\S]*$/, "").trim() || entry.content.slice(0, 40);
+    }
+    return entry;
+  });
+  const explicitPlatform = asString(params.platform);
+  const normalizedPlatform = explicitPlatform?.toLowerCase();
+  let platform;
+  if (explicitPlatform) {
+    if (normalizedPlatform && KNOWN_PLATFORMS.has(normalizedPlatform)) {
+      platform = normalizedPlatform;
+    } else {
+      warn(
+        `agenr_store: invalid platform "${explicitPlatform}". Expected one of: openclaw, codex, claude-code, plaud. Omitting --platform.`
+      );
+    }
+  } else {
+    platform = inferPlatformFromEntries(processedEntries);
+  }
+  for (const entry of processedEntries) {
+    if (typeof entry.source !== "string") {
+      continue;
+    }
+    const normalizedSource = entry.source.toLowerCase();
+    const hasKnownPrefix = RECOMMENDED_SOURCE_PREFIXES.some(
+      (prefix) => normalizedSource.startsWith(prefix)
+    );
+    if (!hasKnownPrefix) {
+      warn(SOURCE_FORMAT_WARNING);
+      break;
+    }
+  }
   const storeArgs = ["store"];
   if (platform) {
     storeArgs.push("--platform", platform);
@@ -388,13 +475,6 @@ async function runStoreTool(agenrPath, params, pluginConfig) {
   if (project) {
     storeArgs.push("--project", project);
   }
-  const processedEntries = entries.map((e) => {
-    const entry = e && typeof e === "object" ? e : {};
-    if (!entry.subject && typeof entry.content === "string") {
-      entry.subject = entry.content.slice(0, 60).replace(/[.!?][\s\S]*$/, "").trim() || entry.content.slice(0, 40);
-    }
-    return entry;
-  });
   const dedupConfig = pluginConfig?.dedup;
   if (dedupConfig?.aggressive === true) {
     storeArgs.push("--aggressive");
@@ -654,7 +734,8 @@ var plugin = {
             }
             const agenrPath = resolveAgenrPath(config);
             const budget = resolveBudget(config);
-            const recallResult = await runRecall(agenrPath, budget);
+            const project = config?.project?.trim() || void 0;
+            const recallResult = await runRecall(agenrPath, budget, project);
             if (recallResult) {
               const formatted = formatRecallAsMarkdown(recallResult);
               if (formatted.trim()) {
@@ -731,7 +812,8 @@ var plugin = {
               return makeDisabledToolResult();
             }
             const agenrPath = resolveAgenrPath(runtimeConfig);
-            return runRecallTool(agenrPath, params);
+            const defaultProject = runtimeConfig?.project?.trim() || void 0;
+            return runRecallTool(agenrPath, params, defaultProject);
           }
         }
       );
@@ -744,6 +826,11 @@ var plugin = {
             entries: Type.Array(
               Type.Object({
                 content: Type.String({ description: "What to remember." }),
+                subject: Type.Optional(
+                  Type.String({
+                    description: "Short subject label. Inferred from content if omitted."
+                  })
+                ),
                 type: Type.Unsafe({
                   type: "string",
                   enum: [...KNOWLEDGE_TYPES],
@@ -780,7 +867,17 @@ var plugin = {
               return makeDisabledToolResult();
             }
             const agenrPath = resolveAgenrPath(runtimeConfig);
-            return runStoreTool(agenrPath, params, runtimeConfig);
+            const defaultProject = runtimeConfig?.project?.trim() || void 0;
+            const toolConfig = {
+              ...runtimeConfig,
+              logger: api.logger
+            };
+            return runStoreTool(
+              agenrPath,
+              params,
+              toolConfig,
+              defaultProject
+            );
           }
         }
       );

package/openclaw.plugin.json

@@ -2,7 +2,6 @@
   "id": "agenr",
   "name": "agenr Memory",
   "description": "Local memory layer - injects agenr context at session start",
-  "version": "0.8.2",
   "skills": [
     "skills"
   ],
@@ -18,6 +17,10 @@
         "type": "number",
         "description": "Token budget for session-start recall. Default: 2000."
       },
+      "project": {
+        "type": "string",
+        "description": "Project scope for recall and store. Omit for global (default)."
+      },
       "enabled": {
         "type": "boolean",
         "description": "Set false to disable memory injection without uninstalling."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenr",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "openclaw": {
     "extensions": [
       "dist/openclaw-plugin/index.js"
@@ -11,13 +11,6 @@
   "bin": {
     "agenr": "dist/cli.js"
   },
-  "scripts": {
-    "build": "tsup src/cli.ts src/cli-main.ts src/openclaw-plugin/index.ts --format esm --dts",
-    "dev": "tsup src/cli.ts src/cli-main.ts --format esm --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
     "@clack/prompts": "^1.0.1",
     "@libsql/client": "^0.17.0",
@@ -61,9 +54,11 @@
     "README.md"
   ],
   "author": "agenr-ai",
-  "pnpm": {
-    "overrides": {
-      "fast-xml-parser": "^5.3.6"
-    }
+  "scripts": {
+    "build": "tsup src/cli.ts src/cli-main.ts src/openclaw-plugin/index.ts --format esm --dts",
+    "dev": "tsup src/cli.ts src/cli-main.ts --format esm --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
   }
-}
+}