agenticros 0.0.1 → 0.1.1

package/runtime/packages/core/src/memory/__tests__/mem0-provider.test.ts

@@ -0,0 +1,192 @@
+/**
+ * Unit tests for the mem0 backend. We construct Mem0MemoryProvider directly
+ * with a hand-rolled fake mem0 Memory instance, so the real `mem0ai` package
+ * is never loaded. This keeps the test fast and dependency-free.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { Mem0MemoryProvider } from "../mem0/provider.js";
+
+interface FakeMem0Call {
+  method: string;
+  args: unknown[];
+}
+
+function createFakeMemory() {
+  const calls: FakeMem0Call[] = [];
+  const records: Array<{ id: string; memory: string; userId: string; metadata: any; score?: number }> = [];
+  let nextId = 1;
+  return {
+    calls,
+    records,
+    async add(content: string, options: any) {
+      calls.push({ method: "add", args: [content, options] });
+      const id = `m${nextId++}`;
+      records.push({
+        id,
+        memory: content,
+        userId: options?.userId,
+        metadata: options?.metadata,
+      });
+      return [{ id, memory: content }];
+    },
+    async search(query: string, options: any) {
+      calls.push({ method: "search", args: [query, options] });
+      if (options?.userId) {
+        throw new Error(
+          "Top-level entity parameters [userId] are not supported in search(). Use filters: { user_id: \"...\" } instead.",
+        );
+      }
+      // Real mem0 v3 requires snake_case `user_id` inside filters.
+      const userId = options?.filters?.user_id;
+      if (!userId) {
+        throw new Error(
+          "filters must contain at least one of: user_id, agent_id, run_id.",
+        );
+      }
+      const matches = records
+        .filter((r) => r.userId === userId)
+        .filter((r) => r.memory.toLowerCase().includes(query.toLowerCase()))
+        .slice(0, options?.limit ?? 10)
+        .map((r) => ({ id: r.id, memory: r.memory, score: 0.9, metadata: r.metadata }));
+      return { results: matches };
+    },
+    async delete(id: string) {
+      calls.push({ method: "delete", args: [id] });
+      const i = records.findIndex((r) => r.id === id);
+      if (i >= 0) records.splice(i, 1);
+      return { success: true };
+    },
+    async getAll(options: any) {
+      calls.push({ method: "getAll", args: [options] });
+      const userId = options?.filters?.user_id ?? options?.userId;
+      return records
+        .filter((r) => r.userId === userId)
+        .slice(0, options?.limit ?? 1000)
+        .map((r) => ({ id: r.id, memory: r.memory, metadata: r.metadata }));
+    },
+  };
+}
+
+test("mem0: remember passes namespace as userId and infer:false by default", async () => {
+  const fake = createFakeMemory();
+  const provider = new Mem0MemoryProvider({ memory: fake, inferOnWrite: false });
+  await provider.remember({ namespace: "robotA", content: "remember this", tags: ["pref"] });
+  const addCall = fake.calls.find((c) => c.method === "add");
+  assert.ok(addCall, "add should have been called");
+  const [content, options] = addCall.args as [string, any];
+  assert.equal(content, "remember this");
+  assert.equal(options.userId, "robotA");
+  assert.equal(options.infer, false);
+  assert.deepEqual(options.metadata.tags, ["pref"]);
+  assert.ok(typeof options.metadata.createdAt === "number");
+});
+
+test("mem0: inferOnWrite:true forwards infer:true to add", async () => {
+  const fake = createFakeMemory();
+  const provider = new Mem0MemoryProvider({ memory: fake, inferOnWrite: true });
+  await provider.remember({ namespace: "ns", content: "hi" });
+  const addCall = fake.calls.find((c) => c.method === "add")!;
+  const [, options] = addCall.args as [string, any];
+  assert.equal(options.infer, true);
+});
+
+test("mem0: recall scopes by namespace via filters.userId and limits results", async () => {
+  const fake = createFakeMemory();
+  const provider = new Mem0MemoryProvider({ memory: fake, inferOnWrite: false });
+  await provider.remember({ namespace: "robotA", content: "kitchen rug" });
+  await provider.remember({ namespace: "robotB", content: "kitchen rug" });
+
+  const hits = await provider.recall({ namespace: "robotA", query: "kitchen", limit: 5 });
+  assert.equal(hits.length, 1, "should only see records for robotA");
+  assert.equal(hits[0].namespace, "robotA");
+
+  const searchCall = fake.calls.find((c) => c.method === "search")!;
+  const [, options] = searchCall.args as [string, any];
+  assert.equal(options.userId, undefined, "must NOT pass top-level userId (mem0 v3+ rejects it)");
+  assert.equal(options.filters.user_id, "robotA", "filters must use snake_case user_id");
+  assert.equal(options.limit, 5);
+});
+
+test("mem0: forget by id calls delete(id)", async () => {
+  const fake = createFakeMemory();
+  const provider = new Mem0MemoryProvider({ memory: fake, inferOnWrite: false });
+  const rec = await provider.remember({ namespace: "ns", content: "x" });
+  const result = await provider.forget({ id: rec.id });
+  assert.equal(result.removed, 1);
+  const delCall = fake.calls.find((c) => c.method === "delete")!;
+  assert.deepEqual(delCall.args, [rec.id]);
+});
+
+test("mem0: forget by query searches and deletes each match", async () => {
+  const fake = createFakeMemory();
+  const provider = new Mem0MemoryProvider({ memory: fake, inferOnWrite: false });
+  await provider.remember({ namespace: "ns", content: "kitchen rug fragile" });
+  await provider.remember({ namespace: "ns", content: "couch is comfortable" });
+
+  const result = await provider.forget({ namespace: "ns", query: "kitchen" });
+  assert.equal(result.removed, 1);
+});
+
+test("mem0: forget by namespace uses enumerate+delete (avoids version-fragile deleteAll)", async () => {
+  const fake = createFakeMemory();
+  // Add a deleteAll spy that should NOT be called.
+  (fake as any).deleteAll = async () => {
+    throw new Error("provider must NOT call deleteAll — mem0 v3 rejects some shapes");
+  };
+  const provider = new Mem0MemoryProvider({ memory: fake, inferOnWrite: false });
+  await provider.remember({ namespace: "ns", content: "a" });
+  await provider.remember({ namespace: "ns", content: "b" });
+  await provider.remember({ namespace: "other", content: "c" });
+
+  const result = await provider.forget({ namespace: "ns" });
+  assert.equal(result.removed, 2);
+  assert.equal(fake.records.length, 1);
+  assert.equal(fake.records[0].userId, "other");
+});
+
+test("mem0: status reports recordCount via getAll + embedder info", async () => {
+  const fake = createFakeMemory();
+  const provider = new Mem0MemoryProvider({
+    memory: fake,
+    inferOnWrite: false,
+    embedder: { provider: "ollama", config: { model: "nomic-embed-text" } },
+  });
+  await provider.remember({ namespace: "ns", content: "fact" });
+  const status = await provider.status("ns");
+  assert.equal(status.backend, "mem0");
+  assert.equal(status.namespace, "ns");
+  assert.equal(status.recordCount, 1);
+  assert.deepEqual(status.embedder, { provider: "ollama", model: "nomic-embed-text" });
+});
+
+test("mem0: recent() sorts by createdAt desc and respects limit and namespace", async () => {
+  const fake = createFakeMemory();
+  const provider = new Mem0MemoryProvider({ memory: fake, inferOnWrite: false });
+
+  // Stage records with explicit metadata.createdAt timestamps (newest -> oldest).
+  await provider.remember({ namespace: "ns", content: "oldest" });
+  await new Promise((r) => setTimeout(r, 2));
+  await provider.remember({ namespace: "ns", content: "middle" });
+  await new Promise((r) => setTimeout(r, 2));
+  await provider.remember({ namespace: "other", content: "other-ns" });
+  await new Promise((r) => setTimeout(r, 2));
+  await provider.remember({ namespace: "ns", content: "newest" });
+
+  const recent = await provider.recent("ns", 5);
+  assert.equal(recent.length, 3, "should only count records in 'ns'");
+  assert.equal(recent[0].content, "newest");
+  assert.equal(recent[1].content, "middle");
+  assert.equal(recent[2].content, "oldest");
+
+  const limited = await provider.recent("ns", 1);
+  assert.equal(limited.length, 1);
+  assert.equal(limited[0].content, "newest");
+
+  // recent() must use the documented v3 filter shape (snake_case user_id in filters).
+  const getAllCall = fake.calls.find(
+    (c) => c.method === "getAll" && (c.args[0] as any)?.filters?.user_id === "ns",
+  );
+  assert.ok(getAllCall, "recent() must filter by filters.user_id");
+});

package/runtime/packages/core/src/memory/__tests__/smart-defaults.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Unit tests for the mem0 embedder auto-detection.
+ * Covers all three branches (Ollama / OpenAI / error) by injecting fetch and env.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { detectEmbedder } from "../mem0/provider.js";
+
+test("smart-defaults: picks Ollama when 11434 responds OK", async () => {
+  const fetchImpl: any = async () => ({ ok: true });
+  const result = await detectEmbedder({
+    fetchImpl,
+    hasOpenAIKey: true, // even with OpenAI present, Ollama wins
+  });
+  assert.equal(result.provider, "ollama");
+  assert.equal((result.config as any).model, "nomic-embed-text");
+});
+
+test("smart-defaults: falls through to OpenAI when Ollama unreachable", async () => {
+  const fetchImpl: any = async () => {
+    throw new Error("ECONNREFUSED");
+  };
+  const result = await detectEmbedder({
+    fetchImpl,
+    hasOpenAIKey: true,
+  });
+  assert.equal(result.provider, "openai");
+  assert.equal((result.config as any).model, "text-embedding-3-small");
+});
+
+test("smart-defaults: throws actionable error when no embedder available", async () => {
+  const fetchImpl: any = async () => {
+    throw new Error("ECONNREFUSED");
+  };
+  await assert.rejects(
+    () => detectEmbedder({ fetchImpl, hasOpenAIKey: false }),
+    /needs an embedder/i,
+  );
+});
+
+test("smart-defaults: Ollama HTTP error (non-OK) falls through to OpenAI", async () => {
+  const fetchImpl: any = async () => ({ ok: false });
+  const result = await detectEmbedder({ fetchImpl, hasOpenAIKey: true });
+  assert.equal(result.provider, "openai");
+});

package/runtime/packages/core/src/memory/factory.ts

@@ -0,0 +1,63 @@
+import type { AgenticROSConfig } from "../config.js";
+import type { MemoryProvider } from "./types.js";
+
+/**
+ * Build a MemoryProvider from full config.
+ *
+ * Returns `null` when memory is disabled (`config.memory.enabled === false`),
+ * so adapters can short-circuit registering memory tools.
+ *
+ * The mem0 backend is loaded via dynamic import — `mem0ai` is an optional peer
+ * dependency. Users on `backend: "local"` never load it.
+ */
+export async function createMemory(
+  config: AgenticROSConfig,
+): Promise<MemoryProvider | null> {
+  if (!config.memory?.enabled) return null;
+
+  const backend = config.memory.backend;
+  switch (backend) {
+    case "local": {
+      const { LocalMemoryProvider } = await import("./local/provider.js");
+      return new LocalMemoryProvider({
+        storePath: config.memory.local.storePath,
+      });
+    }
+
+    case "mem0": {
+      const { createMem0Provider } = await import("./mem0/provider.js");
+      return await createMem0Provider({
+        config: {
+          inferOnWrite: config.memory.mem0.inferOnWrite,
+          historyDbPath: config.memory.mem0.historyDbPath,
+          embedder: config.memory.mem0.embedder,
+          vectorStore: config.memory.mem0.vectorStore,
+          llm: config.memory.mem0.llm,
+        },
+      });
+    }
+
+    default: {
+      const _exhaustive: never = backend;
+      throw new Error(`Unknown memory backend: ${String(_exhaustive)}`);
+    }
+  }
+}
+
+/**
+ * Resolve the effective namespace used by memory tools.
+ * Argument > config.memory.namespace > config.robot.namespace.
+ */
+export function resolveMemoryNamespace(
+  config: AgenticROSConfig,
+  argNamespace?: string,
+): string {
+  return (
+    (argNamespace && argNamespace.trim().length > 0 ? argNamespace : undefined) ??
+    (config.memory?.namespace && config.memory.namespace.trim().length > 0
+      ? config.memory.namespace
+      : undefined) ??
+    config.robot?.namespace ??
+    ""
+  );
+}

package/runtime/packages/core/src/memory/index.ts

@@ -0,0 +1,10 @@
+export type {
+  ForgetInput,
+  MemoryProvider,
+  MemoryRecord,
+  MemoryStatus,
+  RecallInput,
+  RememberInput,
+} from "./types.js";
+
+export { createMemory, resolveMemoryNamespace } from "./factory.js";

package/runtime/packages/core/src/memory/local/provider.ts

@@ -0,0 +1,229 @@
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+import type {
+  ForgetInput,
+  MemoryProvider,
+  MemoryRecord,
+  MemoryStatus,
+  RecallInput,
+  RememberInput,
+} from "../types.js";
+
+interface LocalConfig {
+  storePath: string;
+}
+
+interface FileShape {
+  version: 1;
+  records: MemoryRecord[];
+}
+
+/**
+ * Tiny JSON-on-disk memory backend. No new deps.
+ *
+ * Recall ranks by token-overlap score (tf-style) with a small recency bonus
+ * so two equally-relevant memories are returned newest-first. This is
+ * intentionally dumb — users who want true semantic search opt into mem0.
+ */
+export class LocalMemoryProvider implements MemoryProvider {
+  readonly backend = "local" as const;
+  private readonly storePath: string;
+  private records: MemoryRecord[] | null = null;
+  private writeChain: Promise<void> = Promise.resolve();
+
+  constructor(config: LocalConfig) {
+    this.storePath = expandHome(config.storePath);
+  }
+
+  async remember(input: RememberInput): Promise<MemoryRecord> {
+    const namespace = requireNamespace(input.namespace);
+    const record: MemoryRecord = {
+      id: randomUUID(),
+      content: input.content,
+      namespace,
+      tags: input.tags && input.tags.length > 0 ? [...input.tags] : undefined,
+      path: input.path,
+      createdAt: Date.now(),
+    };
+    const records = await this.load();
+    records.push(record);
+    await this.persist();
+    return cloneRecord(record);
+  }
+
+  async recall(input: RecallInput): Promise<MemoryRecord[]> {
+    const namespace = requireNamespace(input.namespace);
+    const limit = input.limit ?? 10;
+    const records = await this.load();
+    const queryTokens = tokenize(input.query);
+    if (queryTokens.length === 0) return [];
+
+    const now = Date.now();
+    const scored = records
+      .filter((r) => r.namespace === namespace)
+      .map((r) => {
+        const recordTokens = tokenize(r.content);
+        const overlap = overlapScore(queryTokens, recordTokens);
+        const ageMs = Math.max(0, now - r.createdAt);
+        const recencyBonus = Math.exp(-ageMs / (1000 * 60 * 60 * 24 * 14)); // 14-day half-life
+        const score = overlap === 0 ? 0 : overlap + recencyBonus * 0.05;
+        return { record: r, score };
+      })
+      .filter((s) => s.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit);
+
+    return scored.map((s) => ({ ...cloneRecord(s.record), score: s.score }));
+  }
+
+  async forget(input: ForgetInput): Promise<{ removed: number }> {
+    const records = await this.load();
+    const before = records.length;
+    let next: MemoryRecord[];
+
+    if (input.id !== undefined) {
+      next = records.filter((r) => r.id !== input.id);
+    } else if (input.query !== undefined) {
+      const namespace = requireNamespace(input.namespace);
+      const tokens = tokenize(input.query);
+      next = records.filter((r) => {
+        if (r.namespace !== namespace) return true;
+        const overlap = overlapScore(tokens, tokenize(r.content));
+        return overlap === 0;
+      });
+    } else if (input.namespace !== undefined) {
+      next = records.filter((r) => r.namespace !== input.namespace);
+    } else {
+      throw new Error(
+        "forget() requires one of { id }, { query, namespace }, or { namespace }",
+      );
+    }
+
+    if (next.length === before) return { removed: 0 };
+    this.records = next;
+    await this.persist();
+    return { removed: before - next.length };
+  }
+
+  async status(namespace: string): Promise<MemoryStatus> {
+    const records = await this.load();
+    const inNs = records.filter((r) => r.namespace === namespace);
+    const lastWriteAt =
+      inNs.length === 0
+        ? null
+        : inNs.reduce((acc, r) => (r.createdAt > acc ? r.createdAt : acc), 0);
+    return {
+      enabled: true,
+      backend: "local",
+      namespace,
+      recordCount: inNs.length,
+      lastWriteAt,
+    };
+  }
+
+  async recent(namespace: string, limit = 5): Promise<MemoryRecord[]> {
+    const records = await this.load();
+    return records
+      .filter((r) => r.namespace === namespace)
+      .slice()
+      .sort((a, b) => b.createdAt - a.createdAt)
+      .slice(0, Math.max(0, limit))
+      .map(cloneRecord);
+  }
+
+  private async load(): Promise<MemoryRecord[]> {
+    if (this.records !== null) return this.records;
+    try {
+      const raw = await fs.readFile(this.storePath, "utf8");
+      const parsed = JSON.parse(raw) as FileShape;
+      if (
+        parsed &&
+        typeof parsed === "object" &&
+        parsed.version === 1 &&
+        Array.isArray(parsed.records)
+      ) {
+        this.records = parsed.records.map(normalizeRecord);
+      } else {
+        this.records = [];
+      }
+    } catch (err: any) {
+      if (err?.code === "ENOENT") {
+        this.records = [];
+      } else {
+        throw err;
+      }
+    }
+    return this.records;
+  }
+
+  private async persist(): Promise<void> {
+    if (this.records === null) return;
+    const snapshot: FileShape = { version: 1, records: this.records };
+    const text = JSON.stringify(snapshot, null, 2);
+    // Serialize writes so concurrent remember/forget calls don't race.
+    this.writeChain = this.writeChain.then(async () => {
+      await fs.mkdir(path.dirname(this.storePath), { recursive: true });
+      const tmp = `${this.storePath}.tmp`;
+      await fs.writeFile(tmp, text, "utf8");
+      await fs.rename(tmp, this.storePath);
+    });
+    await this.writeChain;
+  }
+}
+
+function expandHome(p: string): string {
+  if (p.startsWith("~/")) return path.join(homedir(), p.slice(2));
+  if (p === "~") return homedir();
+  return p;
+}
+
+function requireNamespace(ns: string | undefined): string {
+  if (!ns || ns.trim().length === 0) {
+    throw new Error(
+      "memory: namespace is required (config.memory.namespace or robot.namespace must be set)",
+    );
+  }
+  return ns;
+}
+
+function tokenize(s: string): string[] {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9_\s]/g, " ")
+    .split(/\s+/)
+    .filter((t) => t.length >= 2);
+}
+
+function overlapScore(query: string[], doc: string[]): number {
+  if (query.length === 0 || doc.length === 0) return 0;
+  const docSet = new Set(doc);
+  let hits = 0;
+  for (const t of query) if (docSet.has(t)) hits += 1;
+  return hits / Math.sqrt(query.length * doc.length);
+}
+
+function cloneRecord(r: MemoryRecord): MemoryRecord {
+  return {
+    id: r.id,
+    content: r.content,
+    namespace: r.namespace,
+    tags: r.tags ? [...r.tags] : undefined,
+    path: r.path,
+    createdAt: r.createdAt,
+    score: r.score,
+  };
+}
+
+function normalizeRecord(r: any): MemoryRecord {
+  return {
+    id: String(r.id ?? randomUUID()),
+    content: String(r.content ?? ""),
+    namespace: String(r.namespace ?? ""),
+    tags: Array.isArray(r.tags) ? r.tags.map(String) : undefined,
+    path: typeof r.path === "string" ? r.path : undefined,
+    createdAt: typeof r.createdAt === "number" ? r.createdAt : Date.now(),
+  };
+}