openclaw-memory-decay 0.1.2

package/README.md

@@ -0,0 +1,323 @@
+![Memory Decay Banner](assets/banner.png)
+
+# openclaw-memory-decay
+
+**Give your OpenClaw a memory — one that forgets.**
+
+An OpenClaw plugin that replaces flat file-based memory with a human-like decay system. Important things stick. Noise fades. Your agent remembers what matters without drowning in everything else.
+
+Built on [memory-decay-core](https://github.com/memory-decay/memory-decay-core) — a mathematical memory model where activation decays over time, stability grows through recall, and retrieval consolidation reinforces what you actually use.
+
+## Why
+
+AI agents forget everything between sessions. The usual fix: dump everything into files and load it all back.
+
+That works. Until it doesn't.
+
+- 50 lines of memory → great. 500 lines → context pollution. 5000 lines → the agent stops attending to what matters.
+- Everything is stored equally. A one-off joke about coffee has the same weight as your API architecture decisions.
+- Retrieval is binary: either it's in the file or it isn't. No notion of "I think I remember this, but I'm not sure."
+
+`openclaw-memory-decay` solves this with **decay**:
+
+- Memories have an activation score that decreases over time — like human forgetting
+- Important memories decay slower; trivial ones fade fast
+- When your agent recalls a memory, it gets reinforced — the testing effect
+- Search results come with freshness indicators: `fresh`, `normal`, `stale`
+- The result: your agent naturally retains what matters and loses what doesn't
+
+```
+Activation
+  1.0 ┤●
+      │ ●●                                     ● (reinforced — recalled)
+  0.8 ┤  ●●                                  ●●●
+      │    ●●●●                            ●●
+  0.6 ┤      ●●●●●●                    ●●●●
+      │            ●●●●●●          ●●●●
+  0.4 ┤                  ●●●●●●●●●●●
+      │    ▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴▴
+  0.2 ┤                                          (unreinforced — fading)
+      │
+  0.0 └─────────────────────────────────────────── Time
+        ● saved at importance 0.9    ▴ saved at importance 0.3
+```
+
+## Features
+
+- **Decay-aware search** — retrieval scores blend semantic similarity with activation and reinforcement history
+- **Automatic noise cleanup** — low-importance memories decay naturally; no manual pruning
+- **Retrieval consolidation** — memories get stronger every time they're recalled, modeling the testing effect
+- **Category-aware storing** — the agent picks the right category (`preference`, `decision`, `fact`, `episode`) with calibrated importance (0.3–1.0), not a flat 0.8 for everything
+- **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
+- **Markdown migration** — imports existing `~/.openclaw/workspace/memory/` files on first run
+
+## Quick Start
+
+```bash
+# 1. Install memory-decay-core (the backend engine)
+pip install memory-decay
+
+# 2. Install this plugin from npm
+openclaw plugins install openclaw-memory-decay
+
+# 3. (Optional but recommended) Restrict auto-load to trusted plugins only
+openclaw config set plugins.allow '["memory-decay"]'
+
+# 4. Restart the gateway
+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`.
+
+### Prerequisites
+
+- [OpenClaw](https://openclaw.ai) installed globally
+- Python 3.10+
+- `memory-decay` Python package (`pip install memory-decay`)
+
+## Configuration
+
+Add to `~/.openclaw/openclaw.json` under `plugins.entries.memory-decay.config`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memory-decay": {
+        "enabled": true,
+        "config": {
+          "dbPath": "~/.openclaw/memory-decay-data/memories.db",
+          "serverPort": 8100,
+          "autoSave": false
+        }
+      }
+    }
+  }
+}
+```
+
+| 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) |
+| `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` |
+| `embeddingApiKey` | (auto) | API key for embedding provider. Falls back to env vars (see below) |
+| `embeddingModel` | (auto) | Specific embedding model name |
+| `embeddingDim` | (auto) | Embedding dimension (auto-detected from provider) |
+
+### API Key Configuration
+
+The API key for embedding providers is resolved in this order:
+
+1. **Plugin config** — `embeddingApiKey` in `openclaw.json`
+2. **Generic env var** — `MD_EMBEDDING_API_KEY`
+3. **Provider-specific env var** — `OPENAI_API_KEY` (openai) or `GEMINI_API_KEY` / `GOOGLE_API_KEY` (gemini)
+
+```bash
+# Example: use OpenAI embeddings with API key from environment
+export OPENAI_API_KEY="sk-..."
+
+# Or use the generic variable (works with any provider)
+export MD_EMBEDDING_API_KEY="sk-..."
+```
+
+When using the `local` provider (default), no API key is needed — embeddings are computed locally using sentence-transformers.
+
+### autoSave: true vs false
+
+| Mode | Who stores | When | Importance |
+|------|-----------|------|------------|
+| `autoSave: true` | Plugin automatically | Every conversation turn | 0.3 (low) |
+| `autoSave: false` | Agent decides | When something is worth remembering | 0.8 (high, set by agent) |
+
+With `autoSave: false`, the agent uses `memory_store` proactively — storing facts, decisions, preferences, and important context. Noise stays out of the memory system entirely.
+
+## Memory Categories
+
+The bootstrap prompt and skills guide the agent to pick the right category and importance:
+
+| Category | When | Importance | Example |
+|----------|------|------------|---------|
+| `preference` | User's role, style, habits, likes/dislikes | 0.8–1.0 | "User prefers Korean for conversation, English for code" |
+| `decision` | Why X was chosen, tradeoffs, rejected alternatives | 0.8–0.9 | "Chose SQLite over Postgres — single-node, no ops overhead" |
+| `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`.
+
+## How It Works
+
+```
+┌──────────────┐         ┌──────────────────┐         ┌────────────────────┐
+│  OpenClaw    │ ◄─────► │  Plugin (TS)     │ ◄─────► │  memory-decay-core │
+│  Agent       │  tools  │  Hook handler    │   HTTP  │  (Python/FastAPI)  │
+│              │         │                  │  :8100  │                    │
+└──────────────┘         └──────────────────┘         └────────────────────┘
+                               │                              │
+                               │ session_end                  │ POST /auto-tick
+                               │ ──────────────►              │
+                               │                              │
+                               │ message_received             │ POST /store
+                               │ (if autoSave)                │
+                               │ ──────────────►              │
+                               │                              │
+                               │ before_compaction            │ POST /store
+                               │                              │
+```
+
+The plugin manages the Python server lifecycle — starts with the gateway, stops on shutdown.
+
+### Memory Lifecycle
+
+```
+  Store ──► Activate ──► Decay ──► Search ──► Reinforce ──► Decay (slower)
+    │                        │                         │
+    │                        │                         └──► Stability increases
+    │                        │
+    │                        └──► Low importance fades fast
+    │                             High importance fades slow
+    │
+    └──► Importance set by agent (0.8) or auto-save (0.3)
+```
+
+1. **Store** — memory enters with an activation of 1.0 and a set importance
+2. **Decay** — each tick, activation decreases based on importance and stability
+3. **Search** — semantic similarity × activation weighting × BM25 re-ranking
+4. **Reinforce** — recalled memories get boosted (testing effect), stability grows
+5. **Forget** — memories with very low activation become practically unretrievable
+
+## Skills
+
+The plugin registers these skills:
+
+| 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 |
+
+## Troubleshooting
+
+### `plugins.allow is empty; discovered non-bundled plugins may auto-load`
+
+This warning appears when `plugins.allow` is not set. While the plugin still loads (since it is explicitly configured in `plugins.entries`), it is good practice to restrict auto-load to trusted plugins only:
+
+```bash
+openclaw config set plugins.allow '["memory-decay"]'
+openclaw gateway restart
+```
+
+### `Cannot find module 'openclaw/plugin-sdk'`
+
+```bash
+openclaw plugins install openclaw-memory-decay
+```
+
+### `Memory service not running`
+
+```bash
+# Check if memory-decay is installed
+pip show memory-decay
+
+# Check server health
+curl http://127.0.0.1:8100/health
+```
+
+If `pip show memory-decay` returns nothing, install it:
+```bash
+pip install memory-decay
+```
+
+### Plugin shows `error` status
+
+```bash
+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.
+
+### 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
+
+# 3. Install plugin from npm
+openclaw plugins install openclaw-memory-decay
+
+# 4. Restart gateway
+openclaw gateway restart
+
+# 5. Verify plugin is loaded
+openclaw plugins list
+# Look for: memory-decay | loaded
+
+# 6. Check server health
+curl -s http://127.0.0.1:8100/health
+# Expected: {"status":"ok","current_tick":0}
+```
+
+### Diagnosing Issues
+
+**Plugin shows `error` status:**
+```bash
+openclaw plugins doctor
+# Check the error message for missing dependencies or path issues
+```
+
+**`Cannot find module 'openclaw/plugin-sdk'`:**
+```bash
+openclaw plugins install openclaw-memory-decay
+```
+
+**`Memory service not running`:**
+```bash
+# Check backend is installed
+pip show memory-decay
+
+# Check if gateway started it
+curl -s http://127.0.0.1:8100/health
+
+# If pip show returns nothing:
+pip install memory-decay
+openclaw gateway restart
+```
+
+**Port conflict (8100 in use):**
+```json
+// In ~/.openclaw/openclaw.json, change:
+"serverPort": 8101
+```
+
+**Embedding errors:**
+```bash
+# Switch to OpenAI if local embeddings fail
+export OPENAI_API_KEY=your-key
+export MD_EMBEDDING_PROVIDER=openai
+openclaw gateway restart
+```
+
+### Key Files
+
+| Path | Purpose |
+|------|---------|
+| `~/.openclaw/openclaw.json` | Plugin configuration |
+| `~/.openclaw/memory-decay-data/memories.db` | Memory database |
+| `~/.openclaw/workspace/memory/` | Legacy memory files (can migrate) |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "openclaw-memory-decay",
+  "version": "0.1.2",
+  "type": "module",
+  "description": "OpenClaw memory plugin backed by memory-decay engine",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src/",
+    "scripts/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/detect-python.mjs",
+    "setup": "node scripts/link-sdk.mjs"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.31.0"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "memory",
+    "ai-agent",
+    "memory-decay"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/memory-decay/openclaw-memory-decay"
+  }
+}

package/scripts/detect-python.mjs

@@ -0,0 +1,35 @@
+#!/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";
+
+const root = dirname(fileURLToPath(import.meta.url));
+const isWin = process.platform === "win32";
+const candidates = isWin ? ["python"] : ["python3", "python"];
+
+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");
+  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}`);

package/scripts/link-sdk.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * Links the global openclaw package into this plugin's node_modules
+ * so that `import ... from "openclaw/plugin-sdk"` resolves correctly.
+ */
+import { existsSync, symlinkSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, "..");
+const target = join(projectRoot, "node_modules", "openclaw");
+
+if (existsSync(target)) {
+  console.log("openclaw SDK already linked.");
+  process.exit(0);
+}
+
+// Find global openclaw installation
+let globalRoot;
+try {
+  globalRoot = execFileSync("npm", ["root", "-g"], { encoding: "utf-8" }).trim();
+} catch {
+  console.error("Failed to find global npm root. Is npm installed?");
+  process.exit(1);
+}
+
+const globalOpenclaw = join(globalRoot, "openclaw");
+if (!existsSync(globalOpenclaw)) {
+  console.error(
+    `openclaw not found at ${globalOpenclaw}\n` +
+    "Install it globally first: npm i -g openclaw"
+  );
+  process.exit(1);
+}
+
+mkdirSync(join(projectRoot, "node_modules"), { recursive: true });
+symlinkSync(globalOpenclaw, target, "junction");
+console.log(`Linked openclaw SDK: ${target} -> ${globalOpenclaw}`);

package/src/client.ts

@@ -0,0 +1,60 @@
+import type {
+  StoreRequest,
+  StoreResponse,
+  SearchRequest,
+  SearchResponse,
+  HealthResponse,
+  AutoTickResponse,
+} from "./types.js";
+
+export class MemoryDecayClient {
+  private baseUrl: string;
+
+  constructor(port: number = 8100) {
+    this.baseUrl = `http://127.0.0.1:${port}`;
+  }
+
+  async health(): Promise<HealthResponse> {
+    const res = await fetch(`${this.baseUrl}/health`);
+    if (!res.ok) throw new Error(`Health check failed: ${res.status}`);
+    return res.json() as Promise<HealthResponse>;
+  }
+
+  async store(req: StoreRequest): Promise<StoreResponse> {
+    const res = await fetch(`${this.baseUrl}/store`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(req),
+    });
+    if (!res.ok) throw new Error(`Store failed: ${res.status}`);
+    return res.json() as Promise<StoreResponse>;
+  }
+
+  async storeBatch(items: StoreRequest[]): Promise<{ ids: string[]; count: number }> {
+    const res = await fetch(`${this.baseUrl}/store-batch`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(items),
+    });
+    if (!res.ok) throw new Error(`Store-batch failed: ${res.status}`);
+    return res.json() as Promise<{ ids: string[]; count: number }>;
+  }
+
+  async search(req: SearchRequest): Promise<SearchResponse> {
+    const res = await fetch(`${this.baseUrl}/search`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(req),
+    });
+    if (!res.ok) throw new Error(`Search failed: ${res.status}`);
+    return res.json() as Promise<SearchResponse>;
+  }
+
+  async autoTick(): Promise<AutoTickResponse> {
+    const res = await fetch(`${this.baseUrl}/auto-tick`, {
+      method: "POST",
+    });
+    if (!res.ok) throw new Error(`Auto-tick failed: ${res.status}`);
+    return res.json() as Promise<AutoTickResponse>;
+  }
+}

package/src/index.ts

@@ -0,0 +1,315 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+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 { toFreshness } from "./types.js";
+
+const BOOTSTRAP_PROMPT = `## Memory System (memory-decay)
+
+You have access to a decay-aware memory system. Use it actively:
+
+- **memory_search**: Search your memories before responding to recall relevant context.
+  Results include a "freshness" indicator (fresh/normal/stale) — treat stale memories with caution, they may be outdated.
+- **memory_store**: Save important memories proactively — don't wait to be asked.
+- **memory_store_batch**: Save multiple memories at once. More efficient than repeated memory_store calls.
+
+### Category & Importance Guide
+
+ALWAYS set the correct category and importance. Do NOT default everything to "fact" at 0.8.
+
+| Category | When | Importance |
+|----------|------|------------|
+| preference | User's role, likes, style, workflow habits | 0.8-1.0 |
+| decision | Why X was chosen, tradeoffs, rejected alternatives | 0.8-0.9 |
+| fact | Technical facts, API behaviors, architecture | 0.7-0.9 |
+| episode | What was worked on, session context | 0.3-0.6 |
+
+### Store Proactively When:
+- User reveals preferences, expertise, or communication style → preference (0.9)
+- A technical choice is made with tradeoffs → decision (0.8)
+- Non-obvious system behavior is discovered → fact (0.8)
+- A feature or fix is completed → episode (0.5)
+
+**IMPORTANT**: Do NOT write memory files to workspace/memory/ or any file path. Always use memory_store / memory_store_batch tools. They handle persistence, decay, and retrieval automatically.
+
+Your memories naturally decay over time. Frequently recalled memories grow stronger; forgotten ones fade. This is by design.`;
+
+const MIN_MESSAGE_LENGTH = 20;
+
+const memoryDecayPlugin = {
+  id: "memory-decay",
+  name: "Memory Decay",
+  description: "Human-like memory with decay and reinforcement",
+  kind: "memory" as const,
+  configSchema: emptyPluginConfigSchema(),
+
+  register(api: OpenClawPluginApi) {
+    const cfg = api.pluginConfig ?? {};
+    const port = (cfg.serverPort as number) ?? 8100;
+    const autoSave = cfg.autoSave !== false; // default true
+
+    // Shared client — works as long as the server process is listening
+    const client = new MemoryDecayClient(port);
+    let service: MemoryDecayService | null = null;
+
+    // --- Service ---
+    api.registerService({
+      id: "memory-decay-server",
+      async start(ctx) {
+        // Resolve embedding provider: config > env var > default
+        const embeddingProvider =
+          (cfg.embeddingProvider as string) ||
+          process.env.MD_EMBEDDING_PROVIDER ||
+          "local";
+
+        // Resolve embedding model: config > env var
+        const embeddingModel =
+          (cfg.embeddingModel as string) ||
+          process.env.MD_EMBEDDING_MODEL;
+
+        // Resolve embedding API key: config > provider-specific env var > generic env var
+        const embeddingApiKey =
+          (cfg.embeddingApiKey as string) ||
+          process.env.MD_EMBEDDING_API_KEY ||
+          (embeddingProvider === "openai"
+            ? process.env.OPENAI_API_KEY
+            : embeddingProvider === "gemini"
+              ? process.env.GEMINI_API_KEY ?? process.env.GOOGLE_API_KEY
+              : undefined);
+
+        if (!embeddingApiKey && embeddingProvider !== "local") {
+          ctx.logger.warn(
+            `No API key found for embedding provider "${embeddingProvider}". ` +
+            `Set MD_EMBEDDING_API_KEY or ${embeddingProvider === "openai" ? "OPENAI_API_KEY" : "GEMINI_API_KEY"} env var.`
+          );
+        }
+
+        // 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) {
+          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;
+          } catch {}
+        }
+        if (!memoryDecayPath) {
+          ctx.logger.error(
+            "Could not auto-detect memory-decay installation. " +
+            "Run `pip install memory-decay` or set memoryDecayPath in plugin config."
+          );
+          return;
+        }
+
+        const config: ServiceConfig = {
+          pythonPath: pythonPath || "python3",
+          memoryDecayPath,
+          port,
+          dbPath: (cfg.dbPath as string) ?? "~/.openclaw/memory-decay-data/memories.db",
+          embeddingProvider,
+          embeddingModel,
+          embeddingApiKey,
+          embeddingDim: (cfg.embeddingDim as number) ??
+            (process.env.MD_EMBEDDING_DIM ? parseInt(process.env.MD_EMBEDDING_DIM, 10) : undefined),
+          experimentDir: cfg.experimentDir as string | undefined,
+        };
+
+        service = new MemoryDecayService(config);
+        await service.start();
+        ctx.logger.info("Server started");
+      },
+      async stop(ctx) {
+        if (service) {
+          await service.stop();
+          ctx.logger.info("Server stopped");
+        }
+      },
+    });
+
+    // --- Tools ---
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const anyApi = api as any;
+
+    anyApi.registerTool(
+      (toolCtx: any) => ({
+        label: "memory_search",
+        name: "memory_search",
+        description: "Search memories with decay-aware ranking. Returns results with freshness indicators.",
+        parameters: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "Search query text" },
+            top_k: { type: "number", description: "Max results (default 5)" },
+          },
+          required: ["query"],
+        },
+        async execute(toolCallId: string, params: Record<string, unknown>) {
+          const res = await client.search({
+            query: params.query as string,
+            top_k: (params.top_k as number) ?? 5,
+          });
+
+          const enriched = res.results.map((r) => ({
+            ...r,
+            freshness: toFreshness(r.storage_score),
+          }));
+
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify(enriched, null, 2) }],
+          };
+        },
+      }),
+      { names: ["memory_search"] },
+    );
+
+    anyApi.registerTool(
+      (toolCtx: any) => ({
+        label: "memory_store",
+        name: "memory_store",
+        description: "Save an important memory. Use proactively for facts, preferences, decisions.",
+        parameters: {
+          type: "object",
+          properties: {
+            text: { type: "string", description: "The memory content to store" },
+            importance: { type: "number", description: "0.0-1.0, default 0.8 for explicit saves" },
+            category: { type: "string", description: "fact, episode, preference, decision" },
+          },
+          required: ["text"],
+        },
+        async execute(toolCallId: string, params: Record<string, unknown>) {
+          const res = await client.store({
+            text: params.text as string,
+            importance: (params.importance as number) ?? 0.8,
+            category: (params.category as string) ?? "fact",
+            mtype: "fact",
+          });
+
+          return {
+            content: [{ type: "text" as const, text: `Stored memory ${res.id}` }],
+          };
+        },
+      }),
+      { names: ["memory_store"] },
+    );
+
+    anyApi.registerTool(
+      (toolCtx: any) => ({
+        label: "memory_store_batch",
+        name: "memory_store_batch",
+        description:
+          "Save multiple memories at once in a single request. More efficient than calling memory_store repeatedly. Each item can have its own importance and category.",
+        parameters: {
+          type: "object",
+          properties: {
+            items: {
+              type: "array",
+              description: "Array of memories to store",
+              items: {
+                type: "object",
+                properties: {
+                  text: { type: "string", description: "The memory content to store" },
+                  importance: { type: "number", description: "0.0-1.0, default 0.8" },
+                  category: { type: "string", description: "fact, episode, preference, decision" },
+                  mtype: { type: "string", description: "fact or episode, default fact" },
+                },
+                required: ["text"],
+              },
+            },
+          },
+          required: ["items"],
+        },
+        async execute(toolCallId: string, params: Record<string, unknown>) {
+          const items = params.items as Array<Record<string, unknown>>;
+          if (!items || items.length === 0) {
+            return {
+              content: [{ type: "text" as const, text: "No items provided" }],
+            };
+          }
+
+          const storeItems = items.map((item) => ({
+            text: item.text as string,
+            importance: (item.importance as number) ?? 0.8,
+            category: (item.category as string) ?? "fact",
+            mtype: (item.mtype as string) ?? "fact",
+          }));
+
+          const res = await client.storeBatch(storeItems);
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Stored ${res.count} memories: ${res.ids.join(", ")}`,
+              },
+            ],
+          };
+        },
+      }),
+      { names: ["memory_store_batch"] },
+    );
+
+    // --- Hooks ---
+
+    // Bootstrap: inject memory instructions + apply time-based decay
+    api.on("before_prompt_build", async (event, ctx) => {
+      try {
+        await client.autoTick();
+      } catch {
+        // Server might still be starting
+      }
+
+      return { prependSystemContext: BOOTSTRAP_PROMPT };
+    });
+
+    // Auto-save: store every conversation turn at low importance
+    // Only active when autoSave is true (default); when disabled, the agent
+    // is expected to use memory_store proactively instead.
+    if (autoSave) {
+      api.on("message_received", async (event, ctx) => {
+        const content = event.content;
+        if (!content || content.length < MIN_MESSAGE_LENGTH) return;
+
+        try {
+          await client.store({
+            text: content,
+            importance: 0.3,
+            mtype: "episode",
+            speaker: event.from ?? "user",
+          });
+        } catch (err) {
+          api.logger.error(`Auto-save failed: ${err}`);
+        }
+      });
+    }
+
+    // Compaction: save session summary before context is compressed
+    api.on("before_compaction", async (event, ctx) => {
+      try {
+        await client.store({
+          text: `[Session summary] Compaction triggered. Topics discussed in this session.`,
+          importance: 0.7,
+          mtype: "episode",
+        });
+      } catch (err) {
+        api.logger.error(`Compaction save failed: ${err}`);
+      }
+    });
+
+    // Session end: apply time-based decay for elapsed time between sessions
+    api.on("session_end", async (event, ctx) => {
+      try {
+        await client.autoTick();
+      } catch (err) {
+        api.logger.error(`Session-end tick failed: ${err}`);
+      }
+    });
+  },
+};
+
+export default memoryDecayPlugin;

package/src/migrator.ts

@@ -0,0 +1,75 @@
+import { readdir, readFile, writeFile, access } from "node:fs/promises";
+import { join, basename } from "node:path";
+import { MemoryDecayClient } from "./client.js";
+import type { StoreRequest } from "./types.js";
+
+const MIGRATION_MARKER = ".migration-done";
+
+export async function shouldMigrate(persistenceDir: string): Promise<boolean> {
+  try {
+    await access(join(persistenceDir, MIGRATION_MARKER));
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+export async function migrateMarkdownMemories(
+  memoryDir: string,
+  client: MemoryDecayClient,
+  persistenceDir: string,
+): Promise<{ migrated: number; files: number }> {
+  const files = await readdir(memoryDir);
+  const mdFiles = files.filter((f) => f.endsWith(".md"));
+
+  const allItems: StoreRequest[] = [];
+
+  for (const file of mdFiles) {
+    const content = await readFile(join(memoryDir, file), "utf-8");
+    const sections = splitIntoSections(content);
+    const isDateFile = /^\d{4}-\d{2}-\d{2}\.md$/.test(file);
+    const isCurated = file === "MEMORY.md" || file.startsWith("MEMORY");
+
+    const importance = isCurated ? 0.7 : isDateFile ? 0.4 : 0.5;
+
+    for (const section of sections) {
+      if (section.trim().length < 10) continue;
+      allItems.push({
+        text: section.trim(),
+        importance,
+        mtype: isDateFile ? "episode" : "fact",
+        category: isCurated ? "curated" : "migrated",
+      });
+    }
+  }
+
+  if (allItems.length > 0) {
+    for (let i = 0; i < allItems.length; i += 50) {
+      const chunk = allItems.slice(i, i + 50);
+      await client.storeBatch(chunk);
+    }
+  }
+
+  await writeFile(
+    join(persistenceDir, MIGRATION_MARKER),
+    JSON.stringify({ migratedAt: new Date().toISOString(), count: allItems.length, files: mdFiles.length }),
+  );
+
+  return { migrated: allItems.length, files: mdFiles.length };
+}
+
+function splitIntoSections(markdown: string): string[] {
+  const sections = markdown.split(/\n(?=#{1,3} )/);
+  const result: string[] = [];
+
+  for (const section of sections) {
+    if (section.length > 500) {
+      const paragraphs = section.split(/\n\n+/);
+      result.push(...paragraphs);
+    } else {
+      result.push(section);
+    }
+  }
+
+  return result;
+}

package/src/service.ts

@@ -0,0 +1,82 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { MemoryDecayClient } from "./client.js";
+
+export interface ServiceConfig {
+  pythonPath: string;
+  memoryDecayPath: string;
+  port: number;
+  dbPath: string;
+  embeddingProvider?: string;
+  embeddingModel?: string;
+  embeddingApiKey?: string;
+  embeddingDim?: number;
+  experimentDir?: string;
+}
+
+export class MemoryDecayService {
+  private process: ChildProcess | null = null;
+  private client: MemoryDecayClient;
+  private config: ServiceConfig;
+  private restartCount = 0;
+  private maxRestarts = 3;
+
+  constructor(config: ServiceConfig) {
+    this.config = config;
+    this.client = new MemoryDecayClient(config.port);
+  }
+
+  async start(): Promise<void> {
+    const args = [
+      "-m", "memory_decay.server",
+      "--host", "127.0.0.1",
+      "--port", String(this.config.port),
+      "--db-path", this.config.dbPath,
+    ];
+    if (this.config.embeddingProvider) args.push("--embedding-provider", this.config.embeddingProvider);
+    if (this.config.embeddingModel) args.push("--embedding-model", this.config.embeddingModel);
+    if (this.config.embeddingApiKey) args.push("--embedding-api-key", this.config.embeddingApiKey);
+    if (this.config.embeddingDim) args.push("--embedding-dim", String(this.config.embeddingDim));
+    if (this.config.experimentDir) args.push("--experiment-dir", this.config.experimentDir);
+
+    this.process = spawn(this.config.pythonPath, args, {
+      cwd: this.config.memoryDecayPath,
+      env: { ...process.env, PYTHONPATH: `${this.config.memoryDecayPath}/src` },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    this.process.on("exit", (code) => {
+      if (code !== 0 && this.restartCount < this.maxRestarts) {
+        this.restartCount++;
+        console.error(`[memory-decay] Server exited with ${code}, restarting (${this.restartCount}/${this.maxRestarts})`);
+        this.start();
+      }
+    });
+
+    await this.waitForHealth();
+  }
+
+  async stop(): Promise<void> {
+    if (this.process) {
+      this.maxRestarts = 0;
+      this.process.kill("SIGTERM");
+      this.process = null;
+    }
+  }
+
+  getClient(): MemoryDecayClient {
+    return this.client;
+  }
+
+  private async waitForHealth(timeoutMs = 15000): Promise<void> {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      try {
+        await this.client.health();
+        return;
+      } catch {
+        await new Promise((r) => setTimeout(r, 500));
+      }
+    }
+    throw new Error(`[memory-decay] Server failed to start within ${timeoutMs}ms`);
+  }
+}

package/src/types.ts

@@ -0,0 +1,53 @@
+export interface StoreRequest {
+  text: string;
+  importance?: number;
+  category?: string;
+  mtype?: string;
+  associations?: string[];
+  speaker?: string;
+}
+
+export interface StoreResponse {
+  id: string;
+  text: string;
+  tick: number;
+}
+
+export interface SearchRequest {
+  query: string;
+  top_k?: number;
+}
+
+export interface SearchResult {
+  id: string;
+  text: string;
+  score: number;
+  storage_score: number;
+  retrieval_score: number;
+  category: string;
+  created_tick: number;
+  speaker?: string;
+}
+
+export interface SearchResponse {
+  results: SearchResult[];
+}
+
+export interface HealthResponse {
+  status: string;
+  current_tick: number;
+}
+
+export interface AutoTickResponse {
+  ticks_applied: number;
+  current_tick: number;
+  elapsed_seconds: number;
+}
+
+export type Freshness = "fresh" | "normal" | "stale";
+
+export function toFreshness(storageScore: number): Freshness {
+  if (storageScore > 0.7) return "fresh";
+  if (storageScore > 0.3) return "normal";
+  return "stale";
+}