@remnic/core 1.0.1 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joshua Warren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @remnic/core
+
+Framework-agnostic memory engine for AI agents. Orchestration, storage, extraction, search, and trust zones -- all local, all private.
+
+Part of [Remnic](https://github.com/joshuaswarren/remnic), the universal memory layer for AI agents.
+
+## Install
+
+```bash
+npm install @remnic/core
+```
+
+## What it does
+
+Remnic Core is the engine that powers persistent memory across AI agent sessions. It handles:
+
+- **Memory orchestration** -- three-phase flow: recall before sessions, buffer during, extract after
+- **Storage** -- plain markdown files with YAML frontmatter on your local filesystem
+- **Extraction** -- GPT-5.2 or local LLM (Ollama, LM Studio) extracts durable knowledge from conversations
+- **Search** -- hybrid BM25 + vector + reranking via QMD
+- **Trust zones** -- namespace isolation and access control for multi-agent setups
+- **Entity tracking** -- people, projects, tools, and their relationships
+- **Consolidation** -- periodic merging, deduplication, and summarization
+- **Temporal supersession** -- when a new fact writes a conflicting value for the same `entityRef + structuredAttribute` key, the older fact is marked `status: "superseded"` and excluded from recall by default. Opt in to audit/history via `temporalSupersessionIncludeInRecall: true`. Controlled by `temporalSupersessionEnabled` (default `true`). See issue #375.
+
+## Usage
+
+Most users interact with Remnic through a higher-level package:
+
+| Package | Use case |
+|---------|----------|
+| [`@remnic/plugin-openclaw`](https://www.npmjs.com/package/@remnic/plugin-openclaw) | OpenClaw gateway plugin |
+| [`@remnic/cli`](https://www.npmjs.com/package/@remnic/cli) | Standalone CLI and daemon |
+| [`@remnic/server`](https://www.npmjs.com/package/@remnic/server) | Standalone HTTP + MCP server |
+
+Use `@remnic/core` directly when building a custom integration or embedding the memory engine in your own agent framework.
+
+```typescript
+import { Orchestrator } from "@remnic/core";
+```
+
+## Fallback LLM
+
+The core includes a fallback LLM client that resolves providers from your gateway config or OpenClaw's built-in provider catalog. It supports OpenAI-compatible and Anthropic APIs with automatic auth resolution and provider fallback chains.
+
+## License
+
+MIT

package/dist/access-cli.d.ts

@@ -1,5 +1,15 @@
-declare function main(argv?: string[]): Promise<void>;
+type AccessCliOptions = {
+    /**
+     * The calling plugin's own id (e.g. `"openclaw-engram"` when invoked by the
+     * shim binary).  Forwarded to {@link resolveRemnicPluginEntry} so shim CLI
+     * users target their own `plugins.entries["openclaw-engram"]` block instead
+     * of accidentally resolving to the canonical `"openclaw-remnic"` entry when
+     * `plugins.slots.memory` is unset (#403).
+     */
+    preferredId?: string;
+};
+declare function main(argv?: string[], options?: AccessCliOptions): Promise<void>;
 declare function printUsage(): void;
-declare function runCli(argv?: string[]): Promise<void>;
+declare function runCli(argv?: string[], options?: AccessCliOptions): Promise<void>;
 
-export { main, printUsage, runCli };
+export { type AccessCliOptions, main, printUsage, runCli };

package/dist/access-cli.js

@@ -1,76 +1,85 @@
 import {
   Orchestrator
-} from "./chunk-OTFNI3OO.js";
-import "./chunk-UYSKNO6E.js";
-import "./chunk-IFFFR3MR.js";
+} from "./chunk-XMGSSBFX.js";
+import "./chunk-JROGC36Y.js";
+import "./chunk-FSFEQI74.js";
+import "./chunk-W6SL7OFG.js";
 import "./chunk-Z5AAYHUC.js";
-import "./chunk-4A24LIM2.js";
+import "./chunk-S75M5ZRK.js";
 import "./chunk-TPB3I2AC.js";
 import "./chunk-UHGBNIOS.js";
-import "./chunk-ZKYI7UVO.js";
-import "./chunk-LP47L3ZX.js";
+import "./chunk-BTY5RRRF.js";
 import "./chunk-ETOW6ACV.js";
-import "./chunk-GPGBSNKM.js";
+import "./chunk-KVE7R4CG.js";
+import "./chunk-JR4ZC3G4.js";
+import "./chunk-C7VW7C3F.js";
+import "./chunk-K4FLSOR5.js";
 import "./chunk-V3RXWQIE.js";
-import "./chunk-G3AG3KZN.js";
-import "./chunk-2CJCWDMR.js";
-import "./chunk-HG2NKWR2.js";
+import "./chunk-5IZL4DCV.js";
+import "./chunk-YDBIWGNI.js";
+import "./chunk-7DHTMOND.js";
+import "./chunk-S4LX5EBI.js";
 import "./chunk-X7XN6YU4.js";
-import "./chunk-BRK4ODMI.js";
-import "./chunk-C7VW7C3F.js";
+import "./chunk-5NPGSAVB.js";
 import "./chunk-YCN4BVDK.js";
-import "./chunk-L5RPWGFK.js";
-import "./chunk-GJR6D6KC.js";
+import "./chunk-D654IBA6.js";
 import "./chunk-H63EDPFJ.js";
-import "./chunk-WWIQTB2Y.js";
-import "./chunk-6UJQNRIO.js";
-import "./chunk-MWGVGUIS.js";
-import "./chunk-763GUIOU.js";
-import "./chunk-ONRU4L2N.js";
-import "./chunk-MDDAA2AO.js";
+import "./chunk-BKQJBXXX.js";
 import "./chunk-YAZNBMNF.js";
-import "./chunk-2PO5ZRKV.js";
+import "./chunk-ALXMCZEU.js";
+import "./chunk-74JR4N5J.js";
+import "./chunk-LAYN4LDC.js";
+import "./chunk-2VFW5K5U.js";
+import "./chunk-UEYA6UC7.js";
+import "./chunk-NBNN5GOB.js";
+import "./chunk-UPMD5XND.js";
+import "./chunk-FEMOX5AD.js";
 import "./chunk-VEWZZM3H.js";
-import "./chunk-QPKFPHOO.js";
-import "./chunk-V4YC4LUK.js";
-import "./chunk-HLBYLYRD.js";
-import "./chunk-OTAVQCSF.js";
+import "./chunk-PAORGQRI.js";
+import "./chunk-PYXS46O7.js";
 import "./chunk-3QKK7QOS.js";
-import "./chunk-UIYZ5T3I.js";
-import "./chunk-UCYSTFZR.js";
-import "./chunk-J47FNDR7.js";
+import "./chunk-GJQPH5G3.js";
+import "./chunk-JRNQ3RNA.js";
+import "./chunk-MYQWXITD.js";
 import "./chunk-CULXMQJH.js";
-import "./chunk-UV2FO7J4.js";
-import "./chunk-T4WRIV2C.js";
+import "./chunk-E6K4NIEU.js";
+import "./chunk-EABGC2TL.js";
 import "./chunk-LOBRX7VD.js";
-import "./chunk-IZME7KW2.js";
+import "./chunk-HITJFT7E.js";
 import "./chunk-YRMVARQP.js";
-import "./chunk-TVVVQQAK.js";
-import "./chunk-BDFZXRSO.js";
-import "./chunk-LK6SGL53.js";
+import {
+  resolveRemnicPluginEntry
+} from "./chunk-U66YHYC7.js";
+import "./chunk-7PA4OZEU.js";
+import "./chunk-J4IYOZZ5.js";
 import "./chunk-AAI7JARD.js";
-import "./chunk-C6QPK5GG.js";
-import "./chunk-Q6FETXJA.js";
+import "./chunk-7SEAZFFB.js";
 import "./chunk-K6WK37A6.js";
-import "./chunk-SCHEKPYH.js";
-import "./chunk-ORZMT74A.js";
-import "./chunk-B7LOFDVE.js";
+import "./chunk-LK6SGL53.js";
+import "./chunk-3PG3H5TD.js";
 import "./chunk-FYIYMQ5N.js";
 import "./chunk-2NMMFZ5T.js";
 import {
   parseConfig
-} from "./chunk-ISY75RLM.js";
+} from "./chunk-OJFGVJS6.js";
 import "./chunk-Z5LAYHGJ.js";
+import "./chunk-C6QPK5GG.js";
+import "./chunk-GZCUW5IC.js";
+import "./chunk-RCICHSHL.js";
+import "./chunk-EJI5XIBB.js";
+import "./chunk-C2EFFULQ.js";
+import "./chunk-4WMCPJWX.js";
+import "./chunk-6HZ6AO2P.js";
 import "./chunk-JWPLJLDU.js";
-import "./chunk-YNI4S5WT.js";
-import "./chunk-DORBM6OB.js";
+import "./chunk-N53K2EXC.js";
+import "./chunk-URB2WSKZ.js";
+import "./chunk-UVJFDP7P.js";
 import "./chunk-XYIK4LF6.js";
-import "./chunk-XUHI52HK.js";
-import "./chunk-M5ZBBBJI.js";
-import "./chunk-OOSWAUYB.js";
+import "./chunk-QKAH5B6E.js";
+import "./chunk-KEG4GNGI.js";
+import "./chunk-ODWDQNRE.js";
 import "./chunk-Y27UJK6V.js";
 import "./chunk-UZB5KHKX.js";
-import "./chunk-M5KEYE5E.js";
 import "./chunk-NGAVDO7E.js";
 import {
   readEnvVar,
@@ -78,29 +87,34 @@ import {
 } from "./chunk-MARWOCVP.js";
 import {
   EngramAccessService
-} from "./chunk-QY2BHY5O.js";
-import "./chunk-N5AKDXAI.js";
+} from "./chunk-V7XCAHIB.js";
 import "./chunk-EQINRHYR.js";
-import "./chunk-J3BT33K7.js";
+import "./chunk-POBPGDWI.js";
+import "./chunk-QDYXG4CS.js";
+import "./chunk-QNJMBKFK.js";
 import "./chunk-EEQLFRUM.js";
-import "./chunk-QWUUMMIK.js";
-import "./chunk-U4PV25RD.js";
-import "./chunk-ESSMF2FR.js";
+import "./chunk-QDW3E4RD.js";
+import "./chunk-4NRAJUDS.js";
+import "./chunk-DT5TVLJE.js";
+import "./chunk-TBBDFYXW.js";
+import "./chunk-DGXUHMOV.js";
+import "./chunk-LPSF4OQH.js";
+import "./chunk-XKECPATV.js";
+import "./chunk-ECKDIK5F.js";
+import "./chunk-POMSFKTB.js";
+import "./chunk-U2IQTSBY.js";
+import "./chunk-4KAN3GZ3.js";
+import "./chunk-6ZH4TU6I.js";
+import "./chunk-6PFRXT4K.js";
 import "./chunk-TP4FZJIZ.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-BOUYNNYD.js";
-import "./chunk-DM2T26WE.js";
 import "./chunk-QSVPYQPG.js";
-import "./chunk-YNCQ7E4M.js";
-import "./chunk-HLXVTBF3.js";
+import "./chunk-DM2T26WE.js";
 import "./chunk-M62O4P4T.js";
-import "./chunk-DT5TVLJE.js";
-import "./chunk-KWBU5S5U.js";
-import "./chunk-DGXUHMOV.js";
-import "./chunk-LPSF4OQH.js";
-import "./chunk-XKECPATV.js";
-import "./chunk-6HZ6AO2P.js";
-import "./chunk-QCCCQT3O.js";
+import "./chunk-4DJQYKMN.js";
+import "./chunk-2ODBA7MQ.js";
+import "./chunk-N5AKDXAI.js";
 
 // src/access-cli.ts
 import fs from "fs";
@@ -227,20 +241,21 @@ function parseFloatOption(args, name) {
   }
   return value;
 }
-function loadPluginConfig() {
+function loadPluginConfig(preferredId) {
   const configPath = readEnvVar("OPENCLAW_ENGRAM_CONFIG_PATH") || readEnvVar("OPENCLAW_CONFIG_PATH") || path.join(resolveHomeDir(), ".openclaw", "openclaw.json");
   const raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
-  return raw?.plugins?.entries?.["openclaw-engram"]?.config ?? {};
+  const entry = resolveRemnicPluginEntry(raw, preferredId);
+  return entry?.["config"] ?? {};
 }
-function buildRuntime() {
-  const config = parseConfig(loadPluginConfig());
+function buildRuntime(preferredId) {
+  const config = parseConfig(loadPluginConfig(preferredId));
   return {
     config,
     service: new EngramAccessService(new Orchestrator(config))
   };
 }
-async function runBrowse(args) {
-  const { service } = buildRuntime();
+async function runBrowse(args, preferredId) {
+  const { service } = buildRuntime(preferredId);
   const result = await service.memoryBrowse({
     namespace: getLastOption(args, "namespace"),
     query: getLastOption(args, "query"),
@@ -252,8 +267,8 @@ async function runBrowse(args) {
   });
   console.log(JSON.stringify(result, null, 2));
 }
-async function runStore(args) {
-  const { config, service } = buildRuntime();
+async function runStore(args, preferredId) {
+  const { config, service } = buildRuntime(preferredId);
   const contentFile = getLastOption(args, "content-file");
   const inlineContent = getLastOption(args, "content");
   const content = contentFile ? fs.readFileSync(contentFile, "utf8") : inlineContent;
@@ -276,20 +291,20 @@ async function runStore(args) {
   });
   console.log(JSON.stringify(result, null, 2));
 }
-async function main(argv = process.argv.slice(2)) {
+async function main(argv = process.argv.slice(2), options = {}) {
   const args = parseArgs(argv);
   if (args.command === "browse") {
-    await runBrowse(args);
+    await runBrowse(args, options.preferredId);
     return;
   }
-  await runStore(args);
+  await runStore(args, options.preferredId);
 }
 function printUsage() {
   writeCliOutput(usage());
 }
-async function runCli(argv = process.argv.slice(2)) {
+async function runCli(argv = process.argv.slice(2), options = {}) {
   try {
-    await main(argv);
+    await main(argv, options);
   } catch (error) {
     if (error instanceof UsageError) {
       writeCliOutput(formatUsageError(error));

package/dist/access-cli.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/access-cli.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { parseConfig } from \"./config.js\";\nimport type { PluginConfig } from \"./types.js\";\nimport { Orchestrator } from \"./orchestrator.js\";\nimport { EngramAccessService } from \"./access-service.js\";\nimport { readEnvVar, resolveHomeDir } from \"./runtime/env.js\";\n\ntype CommandName = \"browse\" | \"store\";\n\ntype ParsedArgs = {\n  command: CommandName;\n  options: Record<string, string[]>;\n  flags: Set<string>;\n};\n\ntype Runtime = {\n  config: PluginConfig;\n  service: EngramAccessService;\n};\n\ntype UsageErrorKind =\n  | \"unsupported-command\"\n  | \"unexpected-positional\"\n  | \"missing-option\"\n  | \"missing-content\"\n  | \"invalid-integer\"\n  | \"invalid-number\";\n\nclass UsageError extends Error {\n  constructor(\n    readonly kind: UsageErrorKind,\n    readonly optionName?: string,\n  ) {\n    super(\"invalid access-cli arguments\");\n  }\n}\n\nfunction formatUsageError(error: UsageError): string {\n  switch (error.kind) {\n    case \"unsupported-command\":\n      return \"unsupported command\";\n    case \"unexpected-positional\":\n      return \"unexpected positional argument\";\n    case \"missing-option\":\n      return `missing required option: --${error.optionName ?? \"unknown\"}`;\n    case \"missing-content\":\n      return \"missing required option: --content or --content-file\";\n    case \"invalid-integer\":\n      return `invalid integer for --${error.optionName ?? \"unknown\"}`;\n    case \"invalid-number\":\n      return `invalid number for --${error.optionName ?? \"unknown\"}`;\n  }\n}\n\nfunction writeCliOutput(text: string = \"\"): void {\n  process.stdout.write(`${text}\\n`);\n}\n\nfunction usage(): string {\n  return [\n    \"Usage:\",\n    \"  engram-access browse [options]\",\n    \"  engram-access store [options]\",\n    \"\",\n    \"Browse options:\",\n    \"  --namespace <name>\",\n    \"  --query <text>\",\n    \"  --category <name>\",\n    \"  --status <name>\",\n    \"  --sort <updated_desc|updated_asc|created_desc|created_asc>\",\n    \"  --limit <n>\",\n    \"  --offset <n>\",\n    \"\",\n    \"Store options:\",\n    \"  --namespace <name>\",\n    \"  --session-key <key>\",\n    \"  --principal <principal>\",\n    \"  --content <text> | --content-file <path>\",\n    \"  --category <name>\",\n    \"  --confidence <0-1>\",\n    \"  --tag <tag> (repeatable)\",\n    \"  --entity-ref <ref>\",\n    \"  --ttl <duration>\",\n    \"  --source-reason <text>\",\n    \"  --idempotency-key <key>\",\n    \"  --dry-run\",\n  ].join(\"\\n\");\n}\n\nfunction parseArgs(argv: string[]): ParsedArgs {\n  const [commandRaw, ...rest] = argv;\n  if (commandRaw !== \"browse\" && commandRaw !== \"store\") {\n    throw new UsageError(\"unsupported-command\");\n  }\n\n  const options: Record<string, string[]> = {};\n  const flags = new Set<string>();\n\n  for (let i = 0; i < rest.length; i += 1) {\n    const token = rest[i];\n    if (!token.startsWith(\"--\")) {\n      throw new UsageError(\"unexpected-positional\");\n    }\n    const key = token.slice(2);\n    const next = rest[i + 1];\n    if (!next || next.startsWith(\"--\")) {\n      flags.add(key);\n      continue;\n    }\n    if (!options[key]) {\n      options[key] = [];\n    }\n    options[key].push(next);\n    i += 1;\n  }\n\n  return {\n    command: commandRaw,\n    options,\n    flags,\n  };\n}\n\nfunction getLastOption(args: ParsedArgs, name: string): string | undefined {\n  const values = args.options[name];\n  if (!values || values.length === 0) return undefined;\n  return values[values.length - 1];\n}\n\nfunction getAllOptions(args: ParsedArgs, name: string): string[] {\n  return args.options[name] ?? [];\n}\n\nfunction requireOption(args: ParsedArgs, name: string): string {\n  const value = getLastOption(args, name);\n  if (!value || value.trim().length === 0) {\n    throw new UsageError(\"missing-option\", name);\n  }\n  return value;\n}\n\nfunction parseIntegerOption(args: ParsedArgs, name: string): number | undefined {\n  const raw = getLastOption(args, name);\n  if (!raw) return undefined;\n  const value = parseInt(raw, 10);\n  if (!Number.isFinite(value)) {\n    throw new UsageError(\"invalid-integer\", name);\n  }\n  return value;\n}\n\nfunction parseFloatOption(args: ParsedArgs, name: string): number | undefined {\n  const raw = getLastOption(args, name);\n  if (!raw) return undefined;\n  const value = Number.parseFloat(raw);\n  if (!Number.isFinite(value)) {\n    throw new UsageError(\"invalid-number\", name);\n  }\n  return value;\n}\n\nfunction loadPluginConfig(): Record<string, unknown> {\n  const configPath =\n    readEnvVar(\"OPENCLAW_ENGRAM_CONFIG_PATH\") ||\n    readEnvVar(\"OPENCLAW_CONFIG_PATH\") ||\n    path.join(resolveHomeDir(), \".openclaw\", \"openclaw.json\");\n  const raw = JSON.parse(fs.readFileSync(configPath, \"utf8\"));\n  return raw?.plugins?.entries?.[\"openclaw-engram\"]?.config ?? {};\n}\n\nfunction buildRuntime(): Runtime {\n  const config = parseConfig(loadPluginConfig());\n  return {\n    config,\n    service: new EngramAccessService(new Orchestrator(config)),\n  };\n}\n\nasync function runBrowse(args: ParsedArgs): Promise<void> {\n  const { service } = buildRuntime();\n  const result = await service.memoryBrowse({\n    namespace: getLastOption(args, \"namespace\"),\n    query: getLastOption(args, \"query\"),\n    category: getLastOption(args, \"category\"),\n    status: getLastOption(args, \"status\"),\n    sort: getLastOption(args, \"sort\") as \"updated_desc\" | \"updated_asc\" | \"created_desc\" | \"created_asc\" | undefined,\n    limit: parseIntegerOption(args, \"limit\"),\n    offset: parseIntegerOption(args, \"offset\"),\n  });\n  console.log(JSON.stringify(result, null, 2));\n}\n\nasync function runStore(args: ParsedArgs): Promise<void> {\n  const { config, service } = buildRuntime();\n  const contentFile = getLastOption(args, \"content-file\");\n  const inlineContent = getLastOption(args, \"content\");\n  const content = contentFile ? fs.readFileSync(contentFile, \"utf8\") : inlineContent;\n  if (!content || content.trim().length === 0) {\n    throw new UsageError(\"missing-content\");\n  }\n\n  const result = await service.memoryStore({\n    namespace: getLastOption(args, \"namespace\"),\n    sessionKey: getLastOption(args, \"session-key\"),\n    authenticatedPrincipal: getLastOption(args, \"principal\") ?? config.agentAccessHttp.principal,\n    content,\n    category: requireOption(args, \"category\"),\n    confidence: parseFloatOption(args, \"confidence\"),\n    tags: getAllOptions(args, \"tag\"),\n    entityRef: getLastOption(args, \"entity-ref\"),\n    ttl: getLastOption(args, \"ttl\"),\n    sourceReason: getLastOption(args, \"source-reason\"),\n    idempotencyKey: getLastOption(args, \"idempotency-key\"),\n    dryRun: args.flags.has(\"dry-run\"),\n  });\n  console.log(JSON.stringify(result, null, 2));\n}\n\nexport async function main(argv: string[] = process.argv.slice(2)): Promise<void> {\n  const args = parseArgs(argv);\n  if (args.command === \"browse\") {\n    await runBrowse(args);\n    return;\n  }\n  await runStore(args);\n}\n\nexport function printUsage(): void {\n  writeCliOutput(usage());\n}\n\nexport async function runCli(argv: string[] = process.argv.slice(2)): Promise<void> {\n  try {\n    await main(argv);\n  } catch (error) {\n    if (error instanceof UsageError) {\n      writeCliOutput(formatUsageError(error));\n      writeCliOutput();\n      printUsage();\n      process.exit(1);\n    }\n\n    console.error(\"access-cli failed\");\n    process.exit(1);\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/access-cli.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport { parseConfig } from \"./config.js\";\nimport type { PluginConfig } from \"./types.js\";\nimport { Orchestrator } from \"./orchestrator.js\";\nimport { EngramAccessService } from \"./access-service.js\";\nimport { readEnvVar, resolveHomeDir } from \"./runtime/env.js\";\nimport { resolveRemnicPluginEntry } from \"./plugin-id.js\";\n\ntype CommandName = \"browse\" | \"store\";\n\ntype ParsedArgs = {\n  command: CommandName;\n  options: Record<string, string[]>;\n  flags: Set<string>;\n};\n\ntype Runtime = {\n  config: PluginConfig;\n  service: EngramAccessService;\n};\n\nexport type AccessCliOptions = {\n  /**\n   * The calling plugin's own id (e.g. `\"openclaw-engram\"` when invoked by the\n   * shim binary).  Forwarded to {@link resolveRemnicPluginEntry} so shim CLI\n   * users target their own `plugins.entries[\"openclaw-engram\"]` block instead\n   * of accidentally resolving to the canonical `\"openclaw-remnic\"` entry when\n   * `plugins.slots.memory` is unset (#403).\n   */\n  preferredId?: string;\n};\n\ntype UsageErrorKind =\n  | \"unsupported-command\"\n  | \"unexpected-positional\"\n  | \"missing-option\"\n  | \"missing-content\"\n  | \"invalid-integer\"\n  | \"invalid-number\";\n\nclass UsageError extends Error {\n  constructor(\n    readonly kind: UsageErrorKind,\n    readonly optionName?: string,\n  ) {\n    super(\"invalid access-cli arguments\");\n  }\n}\n\nfunction formatUsageError(error: UsageError): string {\n  switch (error.kind) {\n    case \"unsupported-command\":\n      return \"unsupported command\";\n    case \"unexpected-positional\":\n      return \"unexpected positional argument\";\n    case \"missing-option\":\n      return `missing required option: --${error.optionName ?? \"unknown\"}`;\n    case \"missing-content\":\n      return \"missing required option: --content or --content-file\";\n    case \"invalid-integer\":\n      return `invalid integer for --${error.optionName ?? \"unknown\"}`;\n    case \"invalid-number\":\n      return `invalid number for --${error.optionName ?? \"unknown\"}`;\n  }\n}\n\nfunction writeCliOutput(text: string = \"\"): void {\n  process.stdout.write(`${text}\\n`);\n}\n\nfunction usage(): string {\n  return [\n    \"Usage:\",\n    \"  engram-access browse [options]\",\n    \"  engram-access store [options]\",\n    \"\",\n    \"Browse options:\",\n    \"  --namespace <name>\",\n    \"  --query <text>\",\n    \"  --category <name>\",\n    \"  --status <name>\",\n    \"  --sort <updated_desc|updated_asc|created_desc|created_asc>\",\n    \"  --limit <n>\",\n    \"  --offset <n>\",\n    \"\",\n    \"Store options:\",\n    \"  --namespace <name>\",\n    \"  --session-key <key>\",\n    \"  --principal <principal>\",\n    \"  --content <text> | --content-file <path>\",\n    \"  --category <name>\",\n    \"  --confidence <0-1>\",\n    \"  --tag <tag> (repeatable)\",\n    \"  --entity-ref <ref>\",\n    \"  --ttl <duration>\",\n    \"  --source-reason <text>\",\n    \"  --idempotency-key <key>\",\n    \"  --dry-run\",\n  ].join(\"\\n\");\n}\n\nfunction parseArgs(argv: string[]): ParsedArgs {\n  const [commandRaw, ...rest] = argv;\n  if (commandRaw !== \"browse\" && commandRaw !== \"store\") {\n    throw new UsageError(\"unsupported-command\");\n  }\n\n  const options: Record<string, string[]> = {};\n  const flags = new Set<string>();\n\n  for (let i = 0; i < rest.length; i += 1) {\n    const token = rest[i];\n    if (!token.startsWith(\"--\")) {\n      throw new UsageError(\"unexpected-positional\");\n    }\n    const key = token.slice(2);\n    const next = rest[i + 1];\n    if (!next || next.startsWith(\"--\")) {\n      flags.add(key);\n      continue;\n    }\n    if (!options[key]) {\n      options[key] = [];\n    }\n    options[key].push(next);\n    i += 1;\n  }\n\n  return {\n    command: commandRaw,\n    options,\n    flags,\n  };\n}\n\nfunction getLastOption(args: ParsedArgs, name: string): string | undefined {\n  const values = args.options[name];\n  if (!values || values.length === 0) return undefined;\n  return values[values.length - 1];\n}\n\nfunction getAllOptions(args: ParsedArgs, name: string): string[] {\n  return args.options[name] ?? [];\n}\n\nfunction requireOption(args: ParsedArgs, name: string): string {\n  const value = getLastOption(args, name);\n  if (!value || value.trim().length === 0) {\n    throw new UsageError(\"missing-option\", name);\n  }\n  return value;\n}\n\nfunction parseIntegerOption(args: ParsedArgs, name: string): number | undefined {\n  const raw = getLastOption(args, name);\n  if (!raw) return undefined;\n  const value = parseInt(raw, 10);\n  if (!Number.isFinite(value)) {\n    throw new UsageError(\"invalid-integer\", name);\n  }\n  return value;\n}\n\nfunction parseFloatOption(args: ParsedArgs, name: string): number | undefined {\n  const raw = getLastOption(args, name);\n  if (!raw) return undefined;\n  const value = Number.parseFloat(raw);\n  if (!Number.isFinite(value)) {\n    throw new UsageError(\"invalid-number\", name);\n  }\n  return value;\n}\n\nfunction loadPluginConfig(preferredId?: string): Record<string, unknown> {\n  const configPath =\n    readEnvVar(\"OPENCLAW_ENGRAM_CONFIG_PATH\") ||\n    readEnvVar(\"OPENCLAW_CONFIG_PATH\") ||\n    path.join(resolveHomeDir(), \".openclaw\", \"openclaw.json\");\n  const raw = JSON.parse(fs.readFileSync(configPath, \"utf8\"));\n  // Delegate slot → preferredId → PLUGIN_ID → LEGACY_PLUGIN_ID resolution to\n  // the shared helper so all config loaders stay in sync (#403).  Shim CLI\n  // callers pass `preferredId: \"openclaw-engram\"` so legacy shim installs\n  // target their own config block instead of falling through to the canonical\n  // \"openclaw-remnic\" entry.\n  const entry = resolveRemnicPluginEntry(raw, preferredId);\n  return (entry?.[\"config\"] as Record<string, unknown> | undefined) ?? {};\n}\n\nfunction buildRuntime(preferredId?: string): Runtime {\n  const config = parseConfig(loadPluginConfig(preferredId));\n  return {\n    config,\n    service: new EngramAccessService(new Orchestrator(config)),\n  };\n}\n\nasync function runBrowse(args: ParsedArgs, preferredId?: string): Promise<void> {\n  const { service } = buildRuntime(preferredId);\n  const result = await service.memoryBrowse({\n    namespace: getLastOption(args, \"namespace\"),\n    query: getLastOption(args, \"query\"),\n    category: getLastOption(args, \"category\"),\n    status: getLastOption(args, \"status\"),\n    sort: getLastOption(args, \"sort\") as \"updated_desc\" | \"updated_asc\" | \"created_desc\" | \"created_asc\" | undefined,\n    limit: parseIntegerOption(args, \"limit\"),\n    offset: parseIntegerOption(args, \"offset\"),\n  });\n  console.log(JSON.stringify(result, null, 2));\n}\n\nasync function runStore(args: ParsedArgs, preferredId?: string): Promise<void> {\n  const { config, service } = buildRuntime(preferredId);\n  const contentFile = getLastOption(args, \"content-file\");\n  const inlineContent = getLastOption(args, \"content\");\n  const content = contentFile ? fs.readFileSync(contentFile, \"utf8\") : inlineContent;\n  if (!content || content.trim().length === 0) {\n    throw new UsageError(\"missing-content\");\n  }\n\n  const result = await service.memoryStore({\n    namespace: getLastOption(args, \"namespace\"),\n    sessionKey: getLastOption(args, \"session-key\"),\n    authenticatedPrincipal: getLastOption(args, \"principal\") ?? config.agentAccessHttp.principal,\n    content,\n    category: requireOption(args, \"category\"),\n    confidence: parseFloatOption(args, \"confidence\"),\n    tags: getAllOptions(args, \"tag\"),\n    entityRef: getLastOption(args, \"entity-ref\"),\n    ttl: getLastOption(args, \"ttl\"),\n    sourceReason: getLastOption(args, \"source-reason\"),\n    idempotencyKey: getLastOption(args, \"idempotency-key\"),\n    dryRun: args.flags.has(\"dry-run\"),\n  });\n  console.log(JSON.stringify(result, null, 2));\n}\n\nexport async function main(\n  argv: string[] = process.argv.slice(2),\n  options: AccessCliOptions = {},\n): Promise<void> {\n  const args = parseArgs(argv);\n  if (args.command === \"browse\") {\n    await runBrowse(args, options.preferredId);\n    return;\n  }\n  await runStore(args, options.preferredId);\n}\n\nexport function printUsage(): void {\n  writeCliOutput(usage());\n}\n\nexport async function runCli(\n  argv: string[] = process.argv.slice(2),\n  options: AccessCliOptions = {},\n): Promise<void> {\n  try {\n    await main(argv, options);\n  } catch (error) {\n    if (error instanceof UsageError) {\n      writeCliOutput(formatUsageError(error));\n      writeCliOutput();\n      printUsage();\n      process.exit(1);\n    }\n\n    console.error(\"access-cli failed\");\n    process.exit(1);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/access-http.d.ts

@@ -2,10 +2,11 @@ import { IncomingMessage } from 'node:http';
 import { EngramAccessService } from './access-service.js';
 import './types.js';
 import './explicit-capture.js';
-import './orchestrator-CIvLFHx3.js';
+import './orchestrator-B9kwlCep.js';
 import './buffer.js';
 import './storage.js';
-import './memory-projection-store-NxMkbocT.js';
+import './page-versioning.js';
+import './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
 import './port-C1GZFv8h.js';
 import './transcript.js';
@@ -18,7 +19,9 @@ import './negative.js';
 import './recall-state.js';
 import './session-observer-state.js';
 import './embedding-fallback.js';
-import './semantic-consolidation.js';
+import './semantic-consolidation-DrvSYRdB.js';
+import './codex-materialize-CQlLTzke.js';
+import './logger.js';
 import 'zod';
 import './policy-runtime.js';
 import './profiling.js';
@@ -96,6 +99,10 @@ interface EngramAccessHttpServerOptions {
     enableAdapters?: boolean;
     /** Custom adapter registry (defaults to built-in adapters) */
     adapterRegistry?: AdapterRegistry;
+    /** Enable oai-mem-citation blocks in recall responses (issue #379). */
+    citationsEnabled?: boolean;
+    /** Auto-enable citations for Codex adapter connections (issue #379). */
+    citationsAutoDetect?: boolean;
 }
 interface EngramAccessHttpServerStatus {
     running: boolean;

package/dist/access-http.js

@@ -1,31 +1,38 @@
 import {
   EngramAccessHttpServer
-} from "./chunk-ZJLY4QSU.js";
-import "./chunk-CXWFUJR2.js";
+} from "./chunk-PMB3WGDL.js";
+import "./chunk-NSB3WSYS.js";
+import "./chunk-IQT3XTKW.js";
 import "./chunk-MARWOCVP.js";
-import "./chunk-PGK3VUHN.js";
-import "./chunk-QY2BHY5O.js";
-import "./chunk-N5AKDXAI.js";
+import "./chunk-MTLYEMJB.js";
+import "./chunk-V7XCAHIB.js";
 import "./chunk-EQINRHYR.js";
-import "./chunk-J3BT33K7.js";
+import "./chunk-POBPGDWI.js";
+import "./chunk-QDYXG4CS.js";
+import "./chunk-QNJMBKFK.js";
 import "./chunk-EEQLFRUM.js";
-import "./chunk-QWUUMMIK.js";
-import "./chunk-U4PV25RD.js";
-import "./chunk-ESSMF2FR.js";
+import "./chunk-QDW3E4RD.js";
+import "./chunk-4NRAJUDS.js";
+import "./chunk-DT5TVLJE.js";
+import "./chunk-TBBDFYXW.js";
+import "./chunk-DGXUHMOV.js";
+import "./chunk-LPSF4OQH.js";
+import "./chunk-XKECPATV.js";
+import "./chunk-ECKDIK5F.js";
+import "./chunk-POMSFKTB.js";
+import "./chunk-U2IQTSBY.js";
+import "./chunk-4KAN3GZ3.js";
+import "./chunk-6ZH4TU6I.js";
+import "./chunk-6PFRXT4K.js";
 import "./chunk-TP4FZJIZ.js";
 import "./chunk-SCU65EZI.js";
 import "./chunk-BOUYNNYD.js";
-import "./chunk-DM2T26WE.js";
 import "./chunk-QSVPYQPG.js";
-import "./chunk-YNCQ7E4M.js";
-import "./chunk-HLXVTBF3.js";
+import "./chunk-DM2T26WE.js";
 import "./chunk-M62O4P4T.js";
-import "./chunk-DT5TVLJE.js";
-import "./chunk-KWBU5S5U.js";
-import "./chunk-DGXUHMOV.js";
-import "./chunk-LPSF4OQH.js";
-import "./chunk-XKECPATV.js";
-import "./chunk-QCCCQT3O.js";
+import "./chunk-4DJQYKMN.js";
+import "./chunk-2ODBA7MQ.js";
+import "./chunk-N5AKDXAI.js";
 export {
   EngramAccessHttpServer
 };

package/dist/access-mcp.d.ts

@@ -2,10 +2,11 @@ import { Readable, Writable } from 'node:stream';
 import { EngramAccessService } from './access-service.js';
 import './types.js';
 import './explicit-capture.js';
-import './orchestrator-CIvLFHx3.js';
+import './orchestrator-B9kwlCep.js';
 import './buffer.js';
 import './storage.js';
-import './memory-projection-store-NxMkbocT.js';
+import './page-versioning.js';
+import './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
 import './port-C1GZFv8h.js';
 import './transcript.js';
@@ -18,7 +19,9 @@ import './negative.js';
 import './recall-state.js';
 import './session-observer-state.js';
 import './embedding-fallback.js';
-import './semantic-consolidation.js';
+import './semantic-consolidation-DrvSYRdB.js';
+import './codex-materialize-CQlLTzke.js';
+import './logger.js';
 import 'zod';
 import './policy-runtime.js';
 import './profiling.js';
@@ -51,8 +54,14 @@ declare class EngramMcpServer {
      * initialize with the same JSON-RPC id concurrently.
      */
     private initSessionIds;
+    /** Whether oai-mem-citation guidance is explicitly enabled via config. */
+    private readonly citationsEnabled;
+    /** Whether to auto-enable citations for Codex adapter connections. */
+    private readonly citationsAutoDetect;
     constructor(service: EngramAccessService, options?: {
         principal?: string;
+        citationsEnabled?: boolean;
+        citationsAutoDetect?: boolean;
     });
     /** Get clientInfo for a specific MCP session. Returns undefined for non-MCP requests. */
     getClientInfo(sessionId?: string): {
@@ -70,6 +79,24 @@ declare class EngramMcpServer {
     private scheduleFlush;
     private flushBuffer;
     private writeMessage;
+    /**
+     * Determine whether oai-mem-citation guidance should be appended to recall.
+     * Returns true when explicitly enabled via config OR when auto-detect is
+     * active and the current MCP session belongs to a Codex adapter client.
+     *
+     * When no sessionId is provided (e.g., stdio transport where there are no
+     * HTTP headers carrying mcp-session-id), fall back to checking if there is
+     * exactly one known session whose clientInfo matches the Codex pattern.
+     * This covers the common stdio case where a single client connection exists.
+     */
+    private shouldEmitCitations;
+    /** Check whether a clientInfo record identifies a Codex adapter client. */
+    private isCodexClient;
+    /**
+     * Build citation metadata for each recall result that has a path.
+     * Line range defaults to 1-1 when not determinable from the summary.
+     */
+    private buildRecallCitations;
     private callTool;
 }
 

package/dist/access-mcp.js

@@ -1,7 +1,22 @@
 import {
   EngramMcpServer
-} from "./chunk-CXWFUJR2.js";
+} from "./chunk-NSB3WSYS.js";
+import "./chunk-IQT3XTKW.js";
 import "./chunk-MARWOCVP.js";
+import "./chunk-ECKDIK5F.js";
+import "./chunk-POMSFKTB.js";
+import "./chunk-U2IQTSBY.js";
+import "./chunk-4KAN3GZ3.js";
+import "./chunk-6ZH4TU6I.js";
+import "./chunk-6PFRXT4K.js";
+import "./chunk-TP4FZJIZ.js";
+import "./chunk-SCU65EZI.js";
+import "./chunk-BOUYNNYD.js";
+import "./chunk-QSVPYQPG.js";
+import "./chunk-DM2T26WE.js";
+import "./chunk-M62O4P4T.js";
+import "./chunk-4DJQYKMN.js";
+import "./chunk-2ODBA7MQ.js";
 export {
   EngramMcpServer
 };