@tensakulabs/memory 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# Memory Module
+
+Three-tier memory system (hot/warm/cold) with REM Sleep batch consolidation.
+
+## Tiers
+
+| Tier | Storage | TTL | Purpose |
+|------|---------|-----|---------|
+| **Hot** | Local MEMORY.md | Permanent | Agent-specific facts |
+| **Warm** | Shared JSONL | 7 days | Cross-agent working context |
+| **Cold** | mem0 | Permanent | Long-tail semantic search |
+
+## Install
+
+```bash
+git clone https://github.com/tensakulabs/memory-module ~/.pai/memory/rem
+cd ~/.pai/memory/rem
+cp memory-config.example.json memory-config.json
+# Edit memory-config.json for your agent
+```
+
+## Update
+
+```bash
+cd ~/.pai/memory/rem && git pull
+```
+
+Config and data are gitignored — updates never overwrite your settings.
+
+## Usage
+
+### Stage facts during sessions ($0)
+
+```bash
+bun stage.ts "fact text"                          # auto-classify
+bun stage.ts "fact text" --tier hot               # explicit tier
+bun stage.ts "fact text" --context "session info"  # add context
+bun stage.ts --list                                # show pending
+bun stage.ts --count                               # count pending
+```
+
+### Batch process (REM Sleep)
+
+```bash
+bun rem-sleep.ts              # full run
+bun rem-sleep.ts --dry-run    # preview decisions
+bun rem-sleep.ts --stats      # show staging stats
+```
+
+## Configuration
+
+`memory-config.json` (create from `memory-config.example.json`):
+
+```json
+{
+  "agent": "sage",
+  "hot":  { "path": "./MEMORY.md" },
+  "warm": { "path": "./warm.jsonl" },
+  "cold": {
+    "mode": "mcp",
+    "endpoint": "http://localhost:8080",
+    "userId": "justin"
+  },
+  "remSleep": {
+    "maxColdWrites": 5,
+    "dedupThreshold": 0.85,
+    "stagingPath": "./rem-staging.jsonl"
+  }
+}
+```
+
+### Cold mode
+
+- `"mcp"` — For Claude Code agents. Uses `claude -p` to access mem0 MCP tools.
+- `"http"` — For OpenClaw/standalone agents. Direct HTTP to mem0 REST API.
+
+See `examples/` for pre-made configs.
+
+## How REM Sleep works
+
+1. During sessions: `bun stage.ts "fact"` → appends to `rem-staging.jsonl` ($0)
+2. Batch runs periodically (cron, launchd, or manual)
+3. Each fact is classified: hot (agent-specific) / warm (shared) / cold (long-tail)
+4. Cold candidates are deduplicated against mem0 (skip if >85% match)
+5. Max 5 cold writes per run (~$0.005 max cost)
+6. Hot facts are printed as suggestions — never auto-written to MEMORY.md
+
+## Requirements
+
+- [Bun](https://bun.sh) runtime
+- mem0 instance (for cold tier)
+- Claude Code (for MCP mode) or direct mem0 API access (for HTTP mode)

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env bun
+/**
+ * Memory Module CLI
+ *
+ * Three-tier memory system (hot/warm/cold) with REM Sleep batch consolidation.
+ *
+ * Usage:
+ *   memory stage "fact text" [--tier hot|warm|cold] [--context "..."]
+ *   memory stage --list | --count
+ *   memory sleep [--dry-run] [--stats]
+ *   memory init [--path ~/.pai/memory]
+ *   memory config
+ *   memory --help
+ *
+ * Install:
+ *   bun add -g @tensakulabs/memory-module
+ *   # or: bun build --compile cli.ts --outfile memory
+ *
+ * Config:
+ *   memory init                     # creates config at ~/.pai/memory/
+ *   MEMORY_CONFIG=./config.json     # explicit config path
+ *   memory stage --config ./c.json  # per-command config
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,521 @@
+#!/usr/bin/env bun
+// @bun
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
+
+// lib.ts
+var exports_lib = {};
+__export(exports_lib, {
+  readJsonl: () => readJsonl,
+  loadConfig: () => loadConfig,
+  generateId: () => generateId,
+  coldSearch: () => coldSearch,
+  coldAdd: () => coldAdd
+});
+import { readFileSync, existsSync } from "fs";
+import { join, resolve, dirname } from "path";
+var {$ } = globalThis.Bun;
+function loadConfig(explicitPath) {
+  const home = process.env.HOME || "~";
+  const candidates = [];
+  if (explicitPath) {
+    candidates.push(resolve(explicitPath));
+  }
+  if (process.env.MEMORY_CONFIG) {
+    candidates.push(resolve(process.env.MEMORY_CONFIG));
+  }
+  candidates.push(join(home, ".pai", "memory", CONFIG_FILENAME));
+  candidates.push(join(dirname(Bun.main), CONFIG_FILENAME));
+  candidates.push(resolve(CONFIG_FILENAME));
+  const configPath = candidates.find((p) => existsSync(p));
+  if (!configPath) {
+    console.error(`Config not found. Searched:`);
+    for (const c of candidates)
+      console.error(`  - ${c}`);
+    console.error(`
+Run: memory init`);
+    process.exit(1);
+  }
+  const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+  const configDir = dirname(configPath);
+  const config = {
+    agent: raw.agent || "unknown",
+    hot: {
+      path: resolvePath(configDir, raw.hot?.path || "./MEMORY.md")
+    },
+    warm: {
+      path: resolvePath(configDir, raw.warm?.path || "./warm.jsonl"),
+      ttlDays: raw.warm?.ttlDays ?? 7
+    },
+    cold: {
+      mode: raw.cold?.mode || "mcp",
+      endpoint: raw.cold?.endpoint,
+      userId: raw.cold?.userId || "justin"
+    },
+    remSleep: {
+      maxColdWrites: raw.remSleep?.maxColdWrites ?? 5,
+      dedupThreshold: raw.remSleep?.dedupThreshold ?? 0.85,
+      stagingPath: resolvePath(configDir, raw.remSleep?.stagingPath || "./rem-staging.jsonl")
+    }
+  };
+  if (config.cold.mode === "http" && !config.cold.endpoint) {
+    console.error("cold.mode is 'http' but no cold.endpoint specified.");
+    process.exit(1);
+  }
+  return { config, configDir };
+}
+function resolvePath(base, p) {
+  if (p.startsWith("/") || p.startsWith("~"))
+    return p.replace(/^~/, process.env.HOME || "~");
+  return resolve(base, p);
+}
+async function coldSearch(config, query) {
+  if (config.cold.mode === "mcp") {
+    return coldSearchMcp(query, config.cold.userId);
+  } else {
+    return coldSearchHttp(config.cold.endpoint, query, config.cold.userId);
+  }
+}
+async function coldAdd(config, fact) {
+  if (config.cold.mode === "mcp") {
+    return coldAddMcp(fact, config.cold.userId);
+  } else {
+    return coldAddHttp(config.cold.endpoint, fact, config.cold.userId);
+  }
+}
+async function coldSearchMcp(query, userId) {
+  try {
+    const escaped = query.replace(/"/g, "\\\"");
+    const prompt = `Search mem0 for this fact and report if it already exists. Use search_memories with query: "${escaped}" and user_id "${userId}". If results exist with high relevance, respond ONLY with: FOUND|<score>|<matching text>. If no close match, respond ONLY with: NOT_FOUND|0|none. Do not explain.`;
+    const result = await $`claude -p ${prompt} --allowedTools "mcp__mem0__search_memories" 2>/dev/null`.text();
+    const line = result.trim().split(`
+`).pop() || "";
+    if (line.startsWith("FOUND|")) {
+      const parts = line.split("|");
+      return { score: parseFloat(parts[1]) || 0, text: parts[2] || "" };
+    }
+    return { score: 0, text: "" };
+  } catch {
+    return { score: 0, text: "" };
+  }
+}
+async function coldAddMcp(fact, userId) {
+  try {
+    const escaped = fact.replace(/"/g, "\\\"");
+    const prompt = `Add this fact to mem0. Use add_memory with text: "${escaped}" and user_id "${userId}". Respond ONLY with: DONE or FAILED.`;
+    const result = await $`claude -p ${prompt} --allowedTools "mcp__mem0__add_memory" 2>/dev/null`.text();
+    return result.trim().includes("DONE");
+  } catch {
+    return false;
+  }
+}
+async function coldSearchHttp(endpoint, query, userId) {
+  try {
+    const res = await fetch(`${endpoint}/v1/memories/search/`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ query, user_id: userId })
+    });
+    if (!res.ok)
+      return { score: 0, text: "" };
+    const data = await res.json();
+    const top = data.results?.[0];
+    if (top) {
+      return { score: top.score ?? 0, text: top.memory ?? "" };
+    }
+    return { score: 0, text: "" };
+  } catch {
+    return { score: 0, text: "" };
+  }
+}
+async function coldAddHttp(endpoint, fact, userId) {
+  try {
+    const res = await fetch(`${endpoint}/v1/memories/`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ text: fact, user_id: userId })
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+function generateId() {
+  return `rem-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+}
+function readJsonl(path) {
+  if (!existsSync(path))
+    return [];
+  return readFileSync(path, "utf-8").trim().split(`
+`).filter(Boolean).map((line) => JSON.parse(line));
+}
+var CONFIG_FILENAME = "memory-config.json";
+var init_lib = () => {};
+
+// stage.ts
+var exports_stage = {};
+__export(exports_stage, {
+  run: () => run
+});
+import { appendFileSync } from "fs";
+function parseArgs(args) {
+  if (args.includes("--list"))
+    return { command: "list" };
+  if (args.includes("--count"))
+    return { command: "count" };
+  const fact = args.find((a) => !a.startsWith("--"));
+  if (!fact) {
+    console.error('Usage: memory stage "fact text" [--context "..."] [--tier hot|warm|cold]');
+    process.exit(1);
+  }
+  let context = "";
+  const ctxIdx = args.indexOf("--context");
+  if (ctxIdx !== -1 && args[ctxIdx + 1])
+    context = args[ctxIdx + 1];
+  let tierHint = "auto";
+  const tierIdx = args.indexOf("--tier");
+  if (tierIdx !== -1 && args[tierIdx + 1]) {
+    const t = args[tierIdx + 1];
+    if (t === "hot" || t === "warm" || t === "cold")
+      tierHint = t;
+  }
+  return { command: "stage", fact, context, tierHint };
+}
+async function run(args) {
+  const { config } = loadConfig();
+  const STAGING = config.remSleep.stagingPath;
+  const parsed = parseArgs(args);
+  if (parsed.command === "list") {
+    const entries = readJsonl(STAGING).filter((e) => !e.processed);
+    if (entries.length === 0) {
+      console.log("No staged facts.");
+    } else {
+      for (const e of entries) {
+        const hint = e.tier_hint === "auto" ? "" : ` [${e.tier_hint}]`;
+        console.log(`${e.id}: ${e.fact}${hint}`);
+      }
+      console.log(`
+${entries.length} fact(s) pending.`);
+    }
+  } else if (parsed.command === "count") {
+    console.log(readJsonl(STAGING).filter((e) => !e.processed).length);
+  } else {
+    const entry = {
+      id: generateId(),
+      fact: parsed.fact,
+      timestamp: new Date().toISOString(),
+      context: parsed.context || "",
+      tier_hint: parsed.tierHint || "auto",
+      processed: false
+    };
+    appendFileSync(STAGING, JSON.stringify(entry) + `
+`);
+    console.log(`Staged: ${entry.id}`);
+  }
+}
+var init_stage = __esm(() => {
+  init_lib();
+  if (import.meta.main) {
+    run(process.argv.slice(2));
+  }
+});
+
+// rem-sleep.ts
+var exports_rem_sleep = {};
+__export(exports_rem_sleep, {
+  run: () => run2
+});
+import { writeFileSync, appendFileSync as appendFileSync2 } from "fs";
+import { join as join2, dirname as dirname2 } from "path";
+function classify(fact) {
+  if (fact.tier_hint !== "auto") {
+    return { ...fact, tier: fact.tier_hint, reason: `explicit: ${fact.tier_hint}` };
+  }
+  const text = `${fact.fact} ${fact.context}`;
+  const hot = HOT_SIGNALS.reduce((s, r) => s + (r.test(text) ? 1 : 0), 0);
+  const warm = WARM_SIGNALS.reduce((s, r) => s + (r.test(text) ? 1 : 0), 0);
+  const cold = COLD_SIGNALS.reduce((s, r) => s + (r.test(text) ? 1 : 0), 0);
+  if (hot > warm && hot > cold)
+    return { ...fact, tier: "hot", reason: `hot signals: ${hot}` };
+  if (warm > cold)
+    return { ...fact, tier: "warm", reason: `warm signals: ${warm}` };
+  if (cold > 0)
+    return { ...fact, tier: "cold", reason: `cold signals: ${cold}` };
+  return { ...fact, tier: "warm", reason: "default (no strong signals)" };
+}
+function appendToWarm(fact) {
+  const entry = {
+    id: fact.id,
+    fact: fact.fact,
+    origin: "new",
+    created: fact.timestamp,
+    last_access: new Date().toISOString(),
+    access_count: 1,
+    context: fact.context
+  };
+  appendFileSync2(WARM, JSON.stringify(entry) + `
+`);
+}
+async function run2(args) {
+  const dryRun = args.includes("--dry-run");
+  const statsOnly = args.includes("--stats");
+  const allEntries = readJsonl(STAGING);
+  const pending = allEntries.filter((e) => !e.processed);
+  if (statsOnly) {
+    console.log(`Agent: ${config.agent}`);
+    console.log(`Cold mode: ${config.cold.mode}`);
+    console.log(`Total entries: ${allEntries.length}`);
+    console.log(`Pending: ${pending.length}`);
+    console.log(`Processed: ${allEntries.length - pending.length}`);
+    return;
+  }
+  if (pending.length === 0) {
+    console.log("No pending facts. Staging is clean.");
+    return;
+  }
+  console.log(`
+\uD83C\uDF19 REM Sleep [${config.agent}] \u2014 Processing ${pending.length} fact(s)${dryRun ? " [DRY RUN]" : ""}`);
+  console.log(`   Cold mode: ${config.cold.mode} | Max writes: ${config.remSleep.maxColdWrites} | Dedup: ${config.remSleep.dedupThreshold}
+`);
+  const classified = pending.map(classify);
+  const hot = classified.filter((f) => f.tier === "hot");
+  const warm = classified.filter((f) => f.tier === "warm");
+  const cold = classified.filter((f) => f.tier === "cold");
+  console.log(`\uD83D\uDCCA Classification: ${hot.length} hot, ${warm.length} warm, ${cold.length} cold
+`);
+  if (hot.length > 0) {
+    console.log("\uD83D\uDD25 HOT \u2014 Suggested MEMORY.md additions (review manually):");
+    console.log(`   Target: ${config.hot.path}`);
+    for (const f of hot)
+      console.log(`  - ${f.fact}  (${f.reason})`);
+    console.log();
+  }
+  if (warm.length > 0) {
+    console.log("\u2668\uFE0F  WARM \u2014 Cross-agent shared facts:");
+    for (const f of warm) {
+      console.log(`  - ${f.fact}`);
+      if (!dryRun)
+        appendToWarm(f);
+    }
+    console.log(dryRun ? `  \u2192 Would write to ${WARM}
+` : `  \u2192 Written to ${WARM}
+`);
+  }
+  let coldWritten = 0;
+  let coldSkipped = 0;
+  let coldCapped = 0;
+  if (cold.length > 0) {
+    console.log("\uD83E\uDDCA COLD \u2014 Long-tail facts (mem0 candidates):");
+    for (const f of cold) {
+      if (coldWritten >= config.remSleep.maxColdWrites) {
+        console.log(`  \u23F8 ${f.fact}  \u2192 DEFERRED (cap reached)`);
+        coldCapped++;
+        continue;
+      }
+      console.log(`  - ${f.fact}`);
+      if (dryRun) {
+        console.log(`    \u2192 Would search mem0 (${config.cold.mode}) then add if new`);
+        continue;
+      }
+      const match = await coldSearch(config, f.fact);
+      if (match.score >= config.remSleep.dedupThreshold) {
+        console.log(`    \u2192 SKIP (dup: ${(match.score * 100).toFixed(0)}% \u2014 "${match.text.slice(0, 60)}...")`);
+        coldSkipped++;
+      } else {
+        const ok = await coldAdd(config, f.fact);
+        console.log(ok ? `    \u2192 ADDED to mem0` : `    \u2192 FAILED`);
+        if (ok)
+          coldWritten++;
+      }
+    }
+    console.log();
+  }
+  if (!dryRun) {
+    const cappedIds = new Set(cold.slice(config.remSleep.maxColdWrites).map((f) => f.id));
+    const updated = allEntries.map((e) => !e.processed && !cappedIds.has(e.id) ? { ...e, processed: true } : e);
+    writeFileSync(STAGING, updated.map((e) => JSON.stringify(e)).join(`
+`) + `
+`);
+  }
+  const report = {
+    timestamp: new Date().toISOString(),
+    agent: config.agent,
+    coldMode: config.cold.mode,
+    dryRun,
+    staged: pending.length,
+    classified: { hot: hot.length, warm: warm.length, cold: cold.length },
+    written: { cold: coldWritten, warm: dryRun ? 0 : warm.length, hotSuggested: hot.length },
+    skipped: coldSkipped,
+    deferred: coldCapped,
+    cost: `~$${(coldWritten * 0.001).toFixed(4)}`
+  };
+  if (!dryRun)
+    writeFileSync(REPORT, JSON.stringify(report, null, 2));
+  console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+  console.log(`\u2705 REM Sleep [${config.agent}] complete${dryRun ? " (dry run)" : ""}`);
+  console.log(`   Hot: ${hot.length} suggested | Warm: ${dryRun ? 0 : warm.length} written | Cold: ${coldWritten} added, ${coldSkipped} dup, ${coldCapped} deferred`);
+  console.log(`   Cost: ${report.cost}`);
+}
+var config, configDir, STAGING, WARM, REPORT, HOT_SIGNALS, WARM_SIGNALS, COLD_SIGNALS;
+var init_rem_sleep = __esm(() => {
+  init_lib();
+  ({ config, configDir } = loadConfig());
+  STAGING = config.remSleep.stagingPath;
+  WARM = config.warm.path;
+  REPORT = join2(dirname2(STAGING), "last-run.json");
+  HOT_SIGNALS = [
+    /\bmy (model|config|cron|path|key|token|port|setup)\b/i,
+    /\b(localhost|127\.0\.0\.1|~\/|\/home\/)/i,
+    /\b(launchd|plist|systemd|crontab)\b/i,
+    /\b(heartbeat) model\b/i
+  ];
+  WARM_SIGNALS = [
+    /\b(we|our|us|together|both agents|cross-agent)\b/i,
+    /\b(prefers|wants|decided|likes|agreed)\b/i,
+    /\b(strategy|approach|decision|convention)\b/i,
+    /\b(project|milestone|roadmap|plan)\b/i
+  ];
+  COLD_SIGNALS = [
+    /\b(PR #\d+|issue #\d+|bug #\d+)\b/i,
+    /\b(benchmark|pricing|per M tokens)\b/i,
+    /\b(workaround|root cause|known issue)\b/i,
+    /\b(research|found|discovered|learned)\b/i
+  ];
+  if (import.meta.main) {
+    run2(process.argv.slice(2)).catch((err) => {
+      console.error("REM Sleep failed:", err);
+      process.exit(1);
+    });
+  }
+});
+
+// cli.ts
+import { existsSync as existsSync2, mkdirSync, copyFileSync } from "fs";
+import { join as join3, dirname as dirname3, resolve as resolve2 } from "path";
+var VERSION = "0.1.0";
+var HELP = `
+memory v${VERSION} \u2014 Three-tier memory with REM Sleep
+
+Commands:
+  stage "fact"     Stage a fact for batch processing ($0)
+    --tier <t>     Force tier: hot, warm, or cold (default: auto)
+    --context "c"  Add context to the staged fact
+    --list         List all pending staged facts
+    --count        Count pending staged facts
+
+  sleep            Run REM Sleep batch processor
+    --dry-run      Preview decisions without executing
+    --stats        Show staging statistics only
+
+  init             Create config at ~/.pai/memory/
+    --path <dir>   Custom config directory
+
+  config           Show current config and paths
+
+  --help           Show this help
+  --version        Show version
+
+Config search order:
+  1. --config flag
+  2. MEMORY_CONFIG env var
+  3. ~/.pai/memory/memory-config.json
+  4. ./memory-config.json
+`.trim();
+var args = process.argv.slice(2);
+var command = args[0];
+if (!command || command === "--help" || command === "-h") {
+  console.log(HELP);
+  process.exit(0);
+}
+if (command === "--version" || command === "-v") {
+  console.log(`memory v${VERSION}`);
+  process.exit(0);
+}
+var configFlag;
+var configIdx = args.indexOf("--config");
+if (configIdx !== -1 && args[configIdx + 1]) {
+  configFlag = args[configIdx + 1];
+  args.splice(configIdx, 2);
+}
+if (configFlag)
+  process.env.MEMORY_CONFIG = resolve2(configFlag);
+switch (command) {
+  case "stage": {
+    const subArgs = args.slice(1);
+    const mod = await Promise.resolve().then(() => (init_stage(), exports_stage));
+    if (mod.run)
+      await mod.run(subArgs);
+    break;
+  }
+  case "sleep": {
+    const subArgs = args.slice(1);
+    const mod = await Promise.resolve().then(() => (init_rem_sleep(), exports_rem_sleep));
+    if (mod.run)
+      await mod.run(subArgs);
+    break;
+  }
+  case "init": {
+    const home = process.env.HOME || "~";
+    let targetDir = join3(home, ".pai", "memory");
+    const pathIdx = args.indexOf("--path");
+    if (pathIdx !== -1 && args[pathIdx + 1])
+      targetDir = resolve2(args[pathIdx + 1]);
+    const configDest = join3(targetDir, "memory-config.json");
+    const exampleSrc = join3(dirname3(Bun.main), "memory-config.example.json");
+    if (existsSync2(configDest)) {
+      console.log(`Config already exists: ${configDest}`);
+      console.log("Edit it directly or delete to reinitialize.");
+      process.exit(0);
+    }
+    mkdirSync(targetDir, { recursive: true });
+    if (existsSync2(exampleSrc)) {
+      copyFileSync(exampleSrc, configDest);
+      console.log(`Created: ${configDest}`);
+      console.log("Edit this file to configure your agent.");
+    } else {
+      const minimal = JSON.stringify({
+        agent: "my-agent",
+        hot: { path: "./MEMORY.md" },
+        warm: { path: "./warm.jsonl" },
+        cold: { mode: "mcp", endpoint: "http://localhost:8080", userId: "your-user-id" },
+        remSleep: { maxColdWrites: 5, dedupThreshold: 0.85, stagingPath: "./rem-staging.jsonl" }
+      }, null, 2);
+      __require("fs").writeFileSync(configDest, minimal + `
+`);
+      console.log(`Created: ${configDest}`);
+      console.log("Edit this file to configure your agent.");
+    }
+    break;
+  }
+  case "config": {
+    const { loadConfig: loadConfig2 } = await Promise.resolve().then(() => (init_lib(), exports_lib));
+    try {
+      const { config: config2, configDir: configDir2 } = loadConfig2(configFlag);
+      console.log(`Agent: ${config2.agent}`);
+      console.log(`Config dir: ${configDir2}`);
+      console.log(`Hot: ${config2.hot.path}`);
+      console.log(`Warm: ${config2.warm.path} (TTL: ${config2.warm.ttlDays}d)`);
+      console.log(`Cold: ${config2.cold.mode} \u2192 ${config2.cold.endpoint || "MCP"} (user: ${config2.cold.userId})`);
+      console.log(`Staging: ${config2.remSleep.stagingPath}`);
+      console.log(`Max cold writes: ${config2.remSleep.maxColdWrites}`);
+      console.log(`Dedup threshold: ${config2.remSleep.dedupThreshold}`);
+    } catch {
+      console.error("No config found. Run: memory init");
+    }
+    break;
+  }
+  default:
+    console.error(`Unknown command: ${command}`);
+    console.error("Run: memory --help");
+    process.exit(1);
+}

package/dist/lib.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Memory Module — Shared Library
+ *
+ * Config loader, types, and cold tier adapters (MCP vs HTTP).
+ * All scripts import from here. No hardcoded paths anywhere.
+ */
+export interface MemoryConfig {
+    agent: string;
+    hot: {
+        path: string;
+    };
+    warm: {
+        path: string;
+        ttlDays: number;
+    };
+    cold: {
+        mode: "mcp" | "http";
+        endpoint?: string;
+        userId: string;
+    };
+    remSleep: {
+        maxColdWrites: number;
+        dedupThreshold: number;
+        stagingPath: string;
+    };
+}
+export interface StagedFact {
+    id: string;
+    fact: string;
+    timestamp: string;
+    context: string;
+    tier_hint: "auto" | "hot" | "warm" | "cold";
+    processed: boolean;
+}
+export interface ColdSearchResult {
+    score: number;
+    text: string;
+}
+/**
+ * Find and load config. Search order:
+ * 1. Explicit path (--config flag)
+ * 2. MEMORY_CONFIG env var
+ * 3. ~/.pai/memory/memory-config.json (canonical home)
+ * 4. Same directory as the calling script
+ * 5. ./memory-config.json (current working directory)
+ */
+export declare function loadConfig(explicitPath?: string): {
+    config: MemoryConfig;
+    configDir: string;
+};
+/**
+ * Search mem0 for duplicate facts.
+ * Uses MCP (via claude -p) or direct HTTP based on config.
+ */
+export declare function coldSearch(config: MemoryConfig, query: string): Promise<ColdSearchResult>;
+/**
+ * Add a fact to mem0.
+ * Uses MCP (via claude -p) or direct HTTP based on config.
+ */
+export declare function coldAdd(config: MemoryConfig, fact: string): Promise<boolean>;
+export declare function generateId(): string;
+export declare function readJsonl<T>(path: string): T[];