@smyslenny/agent-memory 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 2.1.2 (2026-02-22)
+
+### 🔗 OpenClaw Integration V1 (Cron Synchronization)
+
+- **Capture → Consolidate → Surface closed loop** — agent-memory now integrates seamlessly with OpenClaw's built-in memory cron jobs (`memory-sync`, `memory-tidy`, `memory-surface`) with zero code changes ([DD-0004](docs/design/0004-agent-memory-integration.md))
+- **memory-sync** (14:00 & 22:00): Each new journal bullet is auto-synced to agent-memory via `mcporter call agent-memory.remember` with keyword-based type classification and URI dedup
+- **memory-tidy** (03:00): Triggers `agent-memory.reflect phase=all` (Ebbinghaus decay + tidy + govern) after Markdown consolidation, with consistency spot-check
+- **memory-surface** (14:05 & 22:05): Generates structured `RECENT.md` (≤80 lines) from high-vitality agent-memory entries, with fallback to raw journal reading
+- **Design principle**: Markdown remains source of truth; agent-memory is a derived index layer with best-effort sync
+- **README updated** with full OpenClaw Integration guide
+
+## 2.1.1 (2026-02-21)
+
+### 📝 Documentation
+
+- **Memory-janitor integration guide** — New `examples/openclaw-setup.md` section explaining what a memory janitor is and how to wire it to agent-memory (decay trigger + consistency check) ([PR #2](https://github.com/smysle/agent-memory/pull/2))
+- **Phase 5 prompt template** — New `examples/memory-janitor-phase5.md` with full prompt template for appending decay + consistency phases to an existing janitor cron job
+- Covers Gap 1 (Ebbinghaus decay never fires without external trigger) and Gap 2 (two-store divergence between agent-memory and canonical memory files)
+- Includes configurable conflict resolution strategies (canonical wins / agent-memory wins / manual review)
+
 ## 2.0.0 (2026-02-20)
 
 ### 🎉 Complete Rewrite

package/README.md

@@ -119,6 +119,46 @@ runDecay(db);
 
 **9 MCP Tools:** `remember` · `recall` · `recall_path` · `boot` · `forget` · `link` · `snapshot` · `reflect` · `status`
 
+## 🔗 OpenClaw Integration
+
+AgentMemory works **out of the box** with [OpenClaw](https://github.com/smysle/openclaw)'s built-in memory cron jobs — no code changes required. The integration implements a **Capture → Consolidate → Surface** closed loop that keeps Markdown journals and the structured memory DB in sync automatically.
+
+### How It Works
+
+```
+  Capture (memory-sync)          Consolidate (memory-tidy)        Surface (memory-surface)
+  ─────────────────────          ─────────────────────────        ───────────────────────
+  14:00 & 22:00                  03:00                            14:05 & 22:05
+  Session → daily journal        Compress old dailies             Recall top memories
+  + remember each bullet         Distill → MEMORY.md             → generate RECENT.md
+    into agent-memory DB         + reflect phase=all              (≤80 lines, 3 sections)
+```
+
+| Phase | Cron Job | What Happens | agent-memory Integration |
+|-------|----------|-------------|--------------------------|
+| **Capture** | `memory-sync` | Scans sessions, appends bullets to `memory/YYYY-MM-DD.md` | Each new bullet is also written via `mcporter call agent-memory.remember` with auto-classified type and URI-based dedup |
+| **Consolidate** | `memory-tidy` | Compresses old dailies → weekly summaries, distills `MEMORY.md` | Triggers `agent-memory.reflect phase=all` (decay + tidy + govern) + consistency spot-check |
+| **Surface** | `memory-surface` | Generates short-term context for new sessions | Reads high-vitality memories from agent-memory, outputs structured `RECENT.md` with emotion/knowledge/event sections |
+
+### Key Design Principles
+
+- **Markdown is source of truth** — agent-memory is a derived index layer; all data flows Markdown → DB, never the reverse.
+- **Best-effort sync** — If `mcporter` or agent-memory is unavailable, Markdown operations proceed normally. Failures only log warnings.
+- **URI-based idempotency** — Each journal bullet maps to a unique URI (`event://journal/2026-02-21#2200-1`), so re-runs are safe.
+- **Keyword-based classification** — Bullets are auto-classified as `knowledge`, `emotion`, or `event` using simple keyword rules (no extra model calls).
+
+### Setup
+
+If you're running OpenClaw with the standard memory cron suite (`memory-sync`, `memory-tidy`, `memory-surface`), the integration is **already active** — the cron prompts include agent-memory sync steps. Just make sure:
+
+1. **agent-memory is installed and initialized** — `agent-memory init`
+2. **mcporter bridge is configured** — agent-memory MCP server registered in your mcporter config
+3. **Cron jobs are enabled** — check with `openclaw cron list`
+
+For detailed setup and prompt templates, see:
+- [`examples/openclaw-setup.md`](examples/openclaw-setup.md) — Full setup walkthrough
+- [`docs/design/0004-agent-memory-integration.md`](docs/design/0004-agent-memory-integration.md) — Design document (DD-0004)
+
 ## 🏗️ Architecture
 
 ```

package/dist/bin/agent-memory.js

@@ -853,7 +853,8 @@ async function searchHybrid(db, query, opts) {
   if (!provider || !model) {
     return bm25.slice(0, limit);
   }
-  const qVec = Float32Array.from(await provider.embed(query));
+  const embedFn = provider.embedQuery ?? provider.embed;
+  const qVec = Float32Array.from(await embedFn.call(provider, query));
   const embeddings = listEmbeddings(db, agentId, model);
   const scored = [];
   for (const e of embeddings) {
@@ -886,6 +887,29 @@ async function searchHybrid(db, query, opts) {
 }
 
 // src/search/providers.ts
+var QWEN_DEFAULT_INSTRUCTION = "Given a query, retrieve the most semantically relevant document";
+function getDefaultInstruction(model) {
+  const m = model.toLowerCase();
+  if (m.includes("qwen")) return QWEN_DEFAULT_INSTRUCTION;
+  if (m.includes("gemini")) return null;
+  return null;
+}
+function resolveInstruction(model) {
+  const override = process.env.AGENT_MEMORY_EMBEDDINGS_INSTRUCTION;
+  if (override !== void 0) {
+    const normalized = override.trim();
+    if (!normalized) return null;
+    const lowered = normalized.toLowerCase();
+    if (lowered === "none" || lowered === "off" || lowered === "false" || lowered === "null") return null;
+    return normalized;
+  }
+  return getDefaultInstruction(model);
+}
+function buildQueryInput(query, instructionPrefix) {
+  if (!instructionPrefix) return query;
+  return `Instruct: ${instructionPrefix}
+Query: ${query}`;
+}
 function getEmbeddingProviderFromEnv() {
   const provider = (process.env.AGENT_MEMORY_EMBEDDINGS_PROVIDER ?? "none").toLowerCase();
   if (provider === "none" || provider === "off" || provider === "false") return null;
@@ -894,14 +918,24 @@ function getEmbeddingProviderFromEnv() {
     const model = process.env.AGENT_MEMORY_EMBEDDINGS_MODEL ?? "text-embedding-3-small";
     const baseUrl = process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1";
     if (!apiKey) return null;
-    return createOpenAIProvider({ apiKey, model, baseUrl });
+    const instruction = resolveInstruction(model);
+    return createOpenAIProvider({ apiKey, model, baseUrl, instruction });
+  }
+  if (provider === "gemini" || provider === "google") {
+    const apiKey = process.env.GEMINI_API_KEY ?? process.env.OPENAI_API_KEY;
+    const model = process.env.AGENT_MEMORY_EMBEDDINGS_MODEL ?? "gemini-embedding-001";
+    const baseUrl = process.env.GEMINI_BASE_URL ?? process.env.OPENAI_BASE_URL ?? "https://generativelanguage.googleapis.com/v1beta";
+    if (!apiKey) return null;
+    const instruction = resolveInstruction(model);
+    return createOpenAIProvider({ id: "gemini", apiKey, model, baseUrl, instruction });
   }
   if (provider === "qwen" || provider === "dashscope" || provider === "tongyi") {
     const apiKey = process.env.DASHSCOPE_API_KEY;
     const model = process.env.AGENT_MEMORY_EMBEDDINGS_MODEL ?? "text-embedding-v3";
     const baseUrl = process.env.DASHSCOPE_BASE_URL ?? "https://dashscope.aliyuncs.com";
     if (!apiKey) return null;
-    return createDashScopeProvider({ apiKey, model, baseUrl });
+    const instruction = resolveInstruction(model);
+    return createDashScopeProvider({ apiKey, model, baseUrl, instruction });
   }
   return null;
 }
@@ -918,52 +952,67 @@ function normalizeEmbedding(e) {
 }
 function createOpenAIProvider(opts) {
   const baseUrl = opts.baseUrl ?? "https://api.openai.com/v1";
+  const instructionPrefix = opts.instruction ?? null;
+  async function requestEmbedding(input) {
+    const resp = await fetch(`${baseUrl.replace(/\/$/, "")}/embeddings`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: authHeader(opts.apiKey)
+      },
+      body: JSON.stringify({ model: opts.model, input })
+    });
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "");
+      throw new Error(`OpenAI embeddings failed: ${resp.status} ${resp.statusText} ${body}`.trim());
+    }
+    const data = await resp.json();
+    return normalizeEmbedding(data.data?.[0]?.embedding);
+  }
   return {
-    id: "openai",
+    id: opts.id ?? "openai",
     model: opts.model,
+    instructionPrefix,
     async embed(text) {
-      const resp = await fetch(`${baseUrl.replace(/\/$/, "")}/embeddings`, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          authorization: authHeader(opts.apiKey)
-        },
-        body: JSON.stringify({ model: opts.model, input: text })
-      });
-      if (!resp.ok) {
-        const body = await resp.text().catch(() => "");
-        throw new Error(`OpenAI embeddings failed: ${resp.status} ${resp.statusText} ${body}`.trim());
-      }
-      const data = await resp.json();
-      const emb = data.data?.[0]?.embedding;
-      return normalizeEmbedding(emb);
+      return requestEmbedding(text);
+    },
+    async embedQuery(query) {
+      return requestEmbedding(buildQueryInput(query, instructionPrefix));
     }
   };
 }
 function createDashScopeProvider(opts) {
   const baseUrl = opts.baseUrl ?? "https://dashscope.aliyuncs.com";
+  const instructionPrefix = opts.instruction ?? null;
+  async function requestEmbedding(text) {
+    const resp = await fetch(`${baseUrl.replace(/\/$/, "")}/api/v1/services/embeddings/text-embedding/text-embedding`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: authHeader(opts.apiKey)
+      },
+      body: JSON.stringify({
+        model: opts.model,
+        input: { texts: [text] }
+      })
+    });
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "");
+      throw new Error(`DashScope embeddings failed: ${resp.status} ${resp.statusText} ${body}`.trim());
+    }
+    const data = await resp.json();
+    const emb = data.output?.embeddings?.[0]?.embedding ?? data.output?.embeddings?.[0]?.vector ?? data.output?.embedding ?? data.data?.[0]?.embedding;
+    return normalizeEmbedding(emb);
+  }
   return {
     id: "dashscope",
     model: opts.model,
+    instructionPrefix,
     async embed(text) {
-      const resp = await fetch(`${baseUrl.replace(/\/$/, "")}/api/v1/services/embeddings/text-embedding/text-embedding`, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          authorization: authHeader(opts.apiKey)
-        },
-        body: JSON.stringify({
-          model: opts.model,
-          input: { texts: [text] }
-        })
-      });
-      if (!resp.ok) {
-        const body = await resp.text().catch(() => "");
-        throw new Error(`DashScope embeddings failed: ${resp.status} ${resp.statusText} ${body}`.trim());
-      }
-      const data = await resp.json();
-      const emb = data?.output?.embeddings?.[0]?.embedding ?? data?.output?.embeddings?.[0]?.vector ?? data?.output?.embedding ?? data?.data?.[0]?.embedding;
-      return normalizeEmbedding(emb);
+      return requestEmbedding(text);
+    },
+    async embedQuery(query) {
+      return requestEmbedding(buildQueryInput(query, instructionPrefix));
     }
   };
 }