openclaw-memory-decay 0.1.5 → 0.1.7

package/README.md

@@ -51,14 +51,17 @@ Activation
 - **Proactive agent saves** — the agent stores preferences, decisions, facts, and episodes without being asked
 - **Freshness indicators** — search results include `fresh` / `normal` / `stale` so the agent can judge reliability
 - **Dual-score model** — storage score (can it be found?) and retrieval score (how easily?) are tracked separately
-- **`/remember` skill** — users can explicitly ask the agent to remember something
+- **Memory tools** — the plugin exposes `memory_search`, `memory_store`, and `memory_store_batch`
 - **Markdown migration** — imports existing `~/.openclaw/workspace/memory/` files on first run
 
 ## Quick Start
 
+> Deprecated: installing from a cloned checkout via `openclaw plugins install -l .` is no longer the recommended path. Use the published npm package instead.
+
 ```bash
-# 1. Install memory-decay-core (the backend engine)
-pip install memory-decay
+# 1. Install the backend into a dedicated virtualenv
+python3 -m venv ~/.openclaw/venvs/memory-decay
+~/.openclaw/venvs/memory-decay/bin/pip install memory-decay
 
 # 2. Install this plugin from npm
 openclaw plugins install openclaw-memory-decay
@@ -70,13 +73,44 @@ openclaw config set plugins.allow '["memory-decay"]'
 openclaw gateway restart
 ```
 
-> **Note:** Steps 5 and 6 both succeed silently if the plugin is already loaded — use `openclaw plugins list` to confirm status is `loaded` and origin is `config`.
+> **Note:** If the plugin is already loaded, install may succeed silently. Use `openclaw plugins list` to confirm status is `loaded`.
 
 ### Prerequisites
 
 - [OpenClaw](https://openclaw.ai) installed globally
 - Python 3.10+
-- `memory-decay` Python package (`pip install memory-decay`)
+- A Python virtualenv containing `memory-decay`
+
+## Migration From Deprecated Local Install
+
+If you previously installed this plugin from a local checkout via `openclaw plugins install -l .`, migrate to the npm package. Local/path-based installs are now deprecated in favor of the published npm package.
+
+```bash
+# 1. Install from npm instead
+openclaw plugins install openclaw-memory-decay
+
+# 2. Restart gateway
+openclaw gateway restart
+
+# 3. Verify
+openclaw plugins list | grep memory-decay  # should show: memory-decay | loaded
+curl -s http://127.0.0.1:8100/health       # should show: {"status":"ok","current_tick":0}
+```
+
+If auto-detection does not recover your backend path after migration, set the interpreter explicitly:
+
+```bash
+openclaw config set plugins.entries.memory-decay.config.pythonPath "~/.openclaw/venvs/memory-decay/bin/python"
+openclaw gateway restart
+```
+
+**Your memories are safe.** The SQLite database (`memories.db`) is not affected by plugin reinstallation or migration to npm install.
+
+To update in the future:
+```bash
+openclaw plugins update memory-decay
+openclaw gateway restart
+```
 
 ## Configuration
 
@@ -102,8 +136,8 @@ Add to `~/.openclaw/openclaw.json` under `plugins.entries.memory-decay.config`:
 | Option | Default | Description |
 |--------|---------|-------------|
 | `serverPort` | `8100` | Port for the memory-decay HTTP server |
-| `memoryDecayPath` | (auto) | Path to memory-decay-core. Auto-detected from `pip show memory-decay` if not set |
-| `pythonPath` | `python3` | Path to Python interpreter (use your venv) |
+| `memoryDecayPath` | (auto) | Path to memory-decay-core. Auto-detected from the install-time Python environment if not set |
+| `pythonPath` | `python3` | Path to Python interpreter. Set this explicitly if you use a custom venv path instead of `~/.openclaw/venvs/memory-decay` |
 | `dbPath` | `~/.openclaw/memory-decay-data/memories.db` | SQLite database location |
 | `autoSave` | `true` | Auto-save every conversation turn at low importance. Set `false` to let the agent decide what to save |
 | `embeddingProvider` | `local` | Embedding provider: `local`, `openai`, or `gemini` |
@@ -149,7 +183,7 @@ The bootstrap prompt and skills guide the agent to pick the right category and i
 | `fact` | Technical facts, API behaviors, architecture | 0.7–0.9 | "Auth service returns inconsistent 4xx on token expiry" |
 | `episode` | What was worked on, session context | 0.3–0.6 | "Finished migrating auth middleware" |
 
-The agent stores proactively based on conversation triggers — it doesn't wait for `/remember`.
+The agent stores proactively based on conversation triggers — it doesn't wait to be explicitly asked.
 
 ## How It Works
 
@@ -192,17 +226,15 @@ The plugin manages the Python server lifecycle — starts with the gateway, stop
 4. **Reinforce** — recalled memories get boosted (testing effect), stability grows
 5. **Forget** — memories with very low activation become practically unretrievable
 
-## Skills
+## Tools
 
-The plugin registers these skills:
+The plugin registers these tools:
 
-| Skill | Trigger | Description |
-|-------|---------|-------------|
-| `/remember` | `/remember I prefer dark mode` | Save with correct category and calibrated importance |
-| `/recall` | `/recall what did we decide about the API?` | Search memories with freshness-aware action guidance |
-| `/forget` | `/forget the temp password` | Delete a specific memory |
-| `/memory-status` | `/memory-status` | Show memory count, tick, and decay stats |
-| `/migrate` | `/migrate` | Import Markdown files from `memory/` directory |
+| Tool | Purpose |
+|------|---------|
+| `memory_search` | Search memories with decay-aware ranking and freshness indicators |
+| `memory_store` | Save a single memory with calibrated importance and category |
+| `memory_store_batch` | Save multiple memories efficiently in one call |
 
 ## Troubleshooting
 
@@ -224,16 +256,26 @@ openclaw plugins install openclaw-memory-decay
 ### `Memory service not running`
 
 ```bash
-# Check if memory-decay is installed
-pip show memory-decay
+# Check if the configured Python can import the server
+~/.openclaw/venvs/memory-decay/bin/python -c "import memory_decay.server; print('ok')"
 
 # Check server health
 curl http://127.0.0.1:8100/health
 ```
 
-If `pip show memory-decay` returns nothing, install it:
+If the import check fails, install the backend into a virtualenv and either reactivate that venv before reinstalling the plugin or set `pythonPath` explicitly:
 ```bash
-pip install memory-decay
+python3 -m venv ~/.openclaw/venvs/memory-decay
+~/.openclaw/venvs/memory-decay/bin/pip install memory-decay
+```
+
+### `error: externally-managed-environment`
+
+Your system Python is PEP 668 managed. Install `memory-decay` into a virtualenv instead of the system interpreter:
+
+```bash
+python3 -m venv ~/.openclaw/venvs/memory-decay
+~/.openclaw/venvs/memory-decay/bin/pip install memory-decay
 ```
 
 ### Plugin shows `error` status
@@ -245,27 +287,26 @@ openclaw plugins doctor
 ## For AI Agents: Self-Installation Guide
 
 > This section is written for LLM agents to follow autonomously. If you're a human, use the [Quick Start](#quick-start) section above.
+> Use the published npm package. Do not install this plugin from a cloned checkout unless you are actively developing it.
 
 ### Quick Install (one-shot)
 
 ```bash
-# 1. Install the backend engine (requires Python 3.10+)
-pip install memory-decay
-
-# 2. Verify
-pip show memory-decay | head -3
+# 1. Install the backend into a dedicated virtualenv
+python3 -m venv ~/.openclaw/venvs/memory-decay
+~/.openclaw/venvs/memory-decay/bin/pip install memory-decay
 
-# 3. Install plugin from npm
+# 2. Install plugin from npm
 openclaw plugins install openclaw-memory-decay
 
-# 4. Restart gateway
+# 3. Restart gateway
 openclaw gateway restart
 
-# 5. Verify plugin is loaded
+# 4. Verify plugin is loaded
 openclaw plugins list
 # Look for: memory-decay | loaded
 
-# 6. Check server health
+# 5. Check server health
 curl -s http://127.0.0.1:8100/health
 # Expected: {"status":"ok","current_tick":0}
 ```
@@ -285,14 +326,14 @@ openclaw plugins install openclaw-memory-decay
 
 **`Memory service not running`:**
 ```bash
-# Check backend is installed
-pip show memory-decay
+# Check the configured Python can import the backend server
+~/.openclaw/venvs/memory-decay/bin/python -c "import memory_decay.server; print('ok')"
 
 # Check if gateway started it
 curl -s http://127.0.0.1:8100/health
 
-# If pip show returns nothing:
-pip install memory-decay
+# If the import fails, reinstall into the venv:
+~/.openclaw/venvs/memory-decay/bin/pip install memory-decay
 openclaw gateway restart
 ```
 

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "memory-decay",
   "name": "Memory Decay",
   "description": "Human-like memory with decay and reinforcement for OpenClaw agents",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "configSchema": {
     "type": "object",
     "additionalProperties": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-memory-decay",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "OpenClaw memory plugin backed by memory-decay engine",
   "main": "./src/index.js",
@@ -41,5 +41,8 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/memory-decay/openclaw-memory-decay"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/scripts/detect-python-lib.mjs

@@ -0,0 +1,90 @@
+import { execFileSync as nodeExecFileSync } from "node:child_process";
+import { existsSync as nodeExistsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { homedir as nodeHomedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+
+function resolvePythonPath(command, { execFileSync = nodeExecFileSync, isWin = process.platform === "win32" } = {}) {
+  if (isAbsolute(command)) {
+    return command;
+  }
+
+  const resolver = isWin ? "where" : "which";
+  return execFileSync(resolver, [command], { encoding: "utf8" }).trim().split(/\r?\n/)[0];
+}
+
+export function resolveMemoryDecayPath(moduleFile) {
+  const packageDir = dirname(resolve(moduleFile));
+  const packageParent = dirname(packageDir);
+  return basename(packageParent) === "src" ? dirname(packageParent) : packageParent;
+}
+
+export function buildPythonCandidates({
+  pluginRoot,
+  env = process.env,
+  isWin = process.platform === "win32",
+  existsSync = nodeExistsSync,
+  homedir = nodeHomedir,
+} = {}) {
+  const openclawStateDir = resolve(env.OPENCLAW_HOME || homedir(), ".openclaw");
+  const siblingRoots = [
+    resolve(pluginRoot, "../memory-decay"),
+    resolve(pluginRoot, "../memory-decay-core"),
+  ];
+  const pathCandidates = [];
+
+  if (env.MD_PYTHON_PATH) pathCandidates.push(env.MD_PYTHON_PATH);
+  pathCandidates.push(
+    join(openclawStateDir, "venvs", "memory-decay", isWin ? "Scripts/python.exe" : "bin/python"),
+  );
+  if (env.VIRTUAL_ENV) {
+    pathCandidates.push(join(env.VIRTUAL_ENV, isWin ? "Scripts/python.exe" : "bin/python"));
+  }
+  for (const root of siblingRoots) {
+    pathCandidates.push(join(root, isWin ? ".venv/Scripts/python.exe" : ".venv/bin/python"));
+  }
+
+  const commandCandidates = isWin ? ["python"] : ["python3", "python"];
+  return [...new Set([
+    ...pathCandidates.filter((candidate) => existsSync(candidate)),
+    ...commandCandidates,
+  ])];
+}
+
+export function detectPythonEnv({
+  pluginRoot,
+  env = process.env,
+  isWin = process.platform === "win32",
+  existsSync = nodeExistsSync,
+  execFileSync = nodeExecFileSync,
+  makeTempDir = () => mkdtempSync(join(tmpdir(), "memory-decay-python-env-")),
+  readPathFile = (path) => readFileSync(path, "utf8"),
+  removeTempDir = (path) => rmSync(path, { recursive: true, force: true }),
+} = {}) {
+  for (const candidate of buildPythonCandidates({ pluginRoot, env, isWin, existsSync })) {
+    try {
+      execFileSync(candidate, ["-c", "import memory_decay.server"], { stdio: "ignore" });
+      const tempDir = makeTempDir();
+      const outputPath = join(tempDir, "memory-decay-module-path.txt");
+
+      try {
+        execFileSync(candidate, [
+          "-c",
+          `import memory_decay, pathlib; pathlib.Path(${JSON.stringify(outputPath)}).write_text(str(pathlib.Path(memory_decay.__file__).resolve()))`,
+        ], { stdio: "ignore" });
+      } catch (error) {
+        removeTempDir(tempDir);
+        throw error;
+      }
+
+      const moduleFile = readPathFile(outputPath).trim();
+      removeTempDir(tempDir);
+
+      return {
+        pythonPath: resolvePythonPath(candidate, { execFileSync, isWin }),
+        memoryDecayPath: resolveMemoryDecayPath(moduleFile),
+      };
+    } catch {}
+  }
+
+  return null;
+}

package/scripts/detect-python.mjs

@@ -1,35 +1,19 @@
 #!/usr/bin/env node
-import { execSync } from "node:child_process";
 import { writeFileSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { detectPythonEnv } from "./detect-python-lib.mjs";
 
 const root = dirname(fileURLToPath(import.meta.url));
-const isWin = process.platform === "win32";
-const candidates = isWin ? ["python"] : ["python3", "python"];
+const detected = detectPythonEnv({ pluginRoot: resolve(root, "..") });
 
-const python = candidates.find((py) => {
-  try {
-    execSync(
-      `${py} -c "import memory_decay; import sqlite3; sqlite3.connect(':memory:').enable_load_extension(True)"`,
-      { stdio: "ignore" },
-    );
-    return true;
-  } catch {
-    return false;
-  }
-});
-
-if (!python) {
-  console.warn("[memory-decay] memory_decay not found — run: pip install memory-decay");
+if (!detected) {
+  console.warn(
+    "[memory-decay] memory_decay server not found in an active or sibling Python environment. " +
+    "Install the backend in a venv and rerun install, or set pythonPath in plugin config.",
+  );
   process.exit(0);
 }
 
-const pythonPath = execSync(isWin ? `where ${python}` : `which ${python}`, { encoding: "utf8" }).trim().split("\n")[0];
-const memoryDecayPath = execSync(
-  `${python} -c "import memory_decay,os; print(os.path.dirname(os.path.dirname(memory_decay.__file__)))"`,
-  { encoding: "utf8" }
-).trim();
-
-writeFileSync(resolve(root, "../.python-env.json"), JSON.stringify({ pythonPath, memoryDecayPath }, null, 2));
-console.log(`[memory-decay] Detected: ${pythonPath}`);
+writeFileSync(resolve(root, "../.python-env.json"), JSON.stringify(detected, null, 2));
+console.log(`[memory-decay] Detected: ${detected.pythonPath}`);

package/src/index.ts

@@ -3,6 +3,7 @@ import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { MemoryDecayClient } from "./client.js";
 import { MemoryDecayService, type ServiceConfig } from "./service.js";
 import { shouldMigrate, migrateMarkdownMemories } from "./migrator.js";
+import { detectPythonEnv, mergePythonEnv } from "./python-env.js";
 import { toFreshness } from "./types.js";
 
 const BOOTSTRAP_PROMPT = `## Memory System (memory-decay)
@@ -88,21 +89,30 @@ const memoryDecayPlugin = {
         // Resolve pythonPath + memoryDecayPath: config > .python-env.json (set at install time) > error
         let memoryDecayPath = (cfg.memoryDecayPath as string) ?? "";
         let pythonPath = (cfg.pythonPath as string) ?? "";
-        if (!memoryDecayPath) {
+        let detectedEnv: { memoryDecayPath?: string; pythonPath?: string } = {};
+        const { dirname, resolve } = await import("node:path");
+        const { fileURLToPath } = await import("node:url");
+        const pluginRoot = dirname(fileURLToPath(import.meta.url));
+        if (!memoryDecayPath || !pythonPath) {
           try {
             const { readFileSync } = await import("node:fs");
-            const { resolve, dirname } = await import("node:path");
-            const { fileURLToPath } = await import("node:url");
-            const pluginRoot = dirname(fileURLToPath(import.meta.url));
-            const detected = JSON.parse(readFileSync(resolve(pluginRoot, "../.python-env.json"), "utf8"));
-            if (!pythonPath && detected.pythonPath) pythonPath = detected.pythonPath;
-            if (detected.memoryDecayPath) memoryDecayPath = detected.memoryDecayPath;
+            detectedEnv = JSON.parse(readFileSync(resolve(pluginRoot, "../.python-env.json"), "utf8"));
           } catch {}
         }
+        if (!detectedEnv.memoryDecayPath || !detectedEnv.pythonPath) {
+          detectedEnv = mergePythonEnv(
+            detectedEnv,
+            detectPythonEnv({ pluginRoot }) ?? {},
+          );
+        }
+        ({ memoryDecayPath, pythonPath } = mergePythonEnv(
+          { memoryDecayPath, pythonPath },
+          detectedEnv,
+        ));
         if (!memoryDecayPath) {
           ctx.logger.error(
             "Could not auto-detect memory-decay installation. " +
-            "Run `pip install memory-decay` or set memoryDecayPath in plugin config."
+            "Install the backend into ~/.openclaw/venvs/memory-decay or set pythonPath/memoryDecayPath in plugin config."
           );
           return;
         }

package/src/python-env.ts

@@ -0,0 +1,133 @@
+import { execFileSync as nodeExecFileSync } from "node:child_process";
+import { existsSync as nodeExistsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { homedir as nodeHomedir, tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+
+export interface PythonEnvLike {
+  memoryDecayPath?: string;
+  pythonPath?: string;
+}
+
+interface DetectPythonEnvOptions {
+  pluginRoot: string;
+  env?: NodeJS.ProcessEnv;
+  isWin?: boolean;
+  homedir?: () => string;
+  existsSync?: (path: string) => boolean;
+  execFileSync?: typeof nodeExecFileSync;
+  makeTempDir?: () => string;
+  readPathFile?: (path: string) => string;
+  removeTempDir?: (path: string) => void;
+}
+
+export function mergePythonEnv(
+  configured: PythonEnvLike,
+  detected: PythonEnvLike = {},
+): { memoryDecayPath: string; pythonPath: string } {
+  return {
+    memoryDecayPath: configured.memoryDecayPath || detected.memoryDecayPath || "",
+    pythonPath: configured.pythonPath || detected.pythonPath || "",
+  };
+}
+
+function resolveOpenClawStateDir(
+  env: NodeJS.ProcessEnv,
+  homedir: () => string,
+): string {
+  return resolve(env.OPENCLAW_HOME || homedir(), ".openclaw");
+}
+
+export function resolveMemoryDecayPath(moduleFile: string): string {
+  const packageDir = dirname(resolve(moduleFile));
+  const packageParent = dirname(packageDir);
+  return basename(packageParent) === "src" ? dirname(packageParent) : packageParent;
+}
+
+export function buildPythonCandidates({
+  pluginRoot,
+  env = process.env,
+  isWin = process.platform === "win32",
+  homedir = nodeHomedir,
+  existsSync = nodeExistsSync,
+}: Omit<DetectPythonEnvOptions, "execFileSync" | "makeTempDir" | "readPathFile" | "removeTempDir">): string[] {
+  const siblingRoots = [
+    resolve(pluginRoot, "../../memory-decay"),
+    resolve(pluginRoot, "../../memory-decay-core"),
+    resolve(pluginRoot, "../memory-decay"),
+    resolve(pluginRoot, "../memory-decay-core"),
+  ];
+  const openclawStateDir = resolveOpenClawStateDir(env, homedir);
+  const recommendedVenv = join(
+    openclawStateDir,
+    "venvs",
+    "memory-decay",
+    isWin ? "Scripts/python.exe" : "bin/python",
+  );
+  const pathCandidates = [
+    env.MD_PYTHON_PATH,
+    recommendedVenv,
+    env.VIRTUAL_ENV
+      ? join(env.VIRTUAL_ENV, isWin ? "Scripts/python.exe" : "bin/python")
+      : undefined,
+    ...siblingRoots.map((root) =>
+      join(root, isWin ? ".venv/Scripts/python.exe" : ".venv/bin/python")),
+  ].filter((candidate): candidate is string => typeof candidate === "string" && candidate.length > 0 && existsSync(candidate));
+
+  const commandCandidates = isWin ? ["python"] : ["python3", "python"];
+  return [...new Set([...pathCandidates, ...commandCandidates])];
+}
+
+function resolvePythonPath(
+  command: string,
+  {
+    execFileSync = nodeExecFileSync,
+    isWin = process.platform === "win32",
+  }: Pick<DetectPythonEnvOptions, "execFileSync" | "isWin"> = {},
+): string {
+  if (isAbsolute(command)) {
+    return command;
+  }
+
+  const resolver = isWin ? "where" : "which";
+  return execFileSync(resolver, [command], { encoding: "utf8" }).trim().split(/\r?\n/)[0];
+}
+
+export function detectPythonEnv({
+  pluginRoot,
+  env = process.env,
+  isWin = process.platform === "win32",
+  homedir = nodeHomedir,
+  existsSync = nodeExistsSync,
+  execFileSync = nodeExecFileSync,
+  makeTempDir = () => mkdtempSync(join(tmpdir(), "memory-decay-python-env-")),
+  readPathFile = (path) => readFileSync(path, "utf8"),
+  removeTempDir = (path) => rmSync(path, { recursive: true, force: true }),
+}: DetectPythonEnvOptions): { memoryDecayPath: string; pythonPath: string } | null {
+  for (const candidate of buildPythonCandidates({ pluginRoot, env, isWin, homedir, existsSync })) {
+    try {
+      execFileSync(candidate, ["-c", "import memory_decay.server"], { stdio: "ignore" });
+      const tempDir = makeTempDir();
+      const outputPath = join(tempDir, "memory-decay-module-path.txt");
+
+      try {
+        execFileSync(candidate, [
+          "-c",
+          `import memory_decay, pathlib; pathlib.Path(${JSON.stringify(outputPath)}).write_text(str(pathlib.Path(memory_decay.__file__).resolve()))`,
+        ], { stdio: "ignore" });
+      } catch (error) {
+        removeTempDir(tempDir);
+        throw error;
+      }
+
+      const moduleFile = readPathFile(outputPath).trim();
+      removeTempDir(tempDir);
+
+      return {
+        pythonPath: resolvePythonPath(candidate, { execFileSync, isWin }),
+        memoryDecayPath: resolveMemoryDecayPath(moduleFile),
+      };
+    } catch {}
+  }
+
+  return null;
+}