@agentmemory/agentmemory 0.9.30 → 0.9.32

package/integrations/openclaw/plugin.mjs

@@ -0,0 +1,425 @@
+/**
+ * agentmemory plugin for OpenClaw
+ *
+ * Deeper integration than raw MCP:
+ * - claims the plugins.slots.memory slot via api.registerMemoryCapability({ promptBuilder })
+ * - recalls relevant memories before the agent starts (before_prompt_build hook)
+ * - captures completed conversation turns after the agent finishes (agent_end hook)
+ *
+ * Requires the agentmemory server on localhost:3111.
+ * Start it with: npx @agentmemory/agentmemory
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+
+const DEFAULT_BASE_URL = "http://localhost:3111";
+const DEFAULT_TIMEOUT_MS = 5000;
+
+const configSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    enabled: { type: "boolean" },
+    base_url: { type: "string" },
+    secret_env: { type: "string", pattern: "^[A-Za-z_][A-Za-z0-9_]*$" },
+    token_budget: { type: "integer", minimum: 0, maximum: 32000 },
+    min_confidence: { type: "number", minimum: 0, maximum: 1 },
+    fallback_on_error: { type: "boolean" },
+    timeout_ms: { type: "integer", minimum: 1, maximum: 60000 },
+  },
+};
+
+function extractText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .flatMap((block) => {
+      if (!block || typeof block !== "object") return [];
+      if (block.type === "text" && typeof block.text === "string") return [block.text];
+      return [];
+    })
+    .join("\n")
+    .trim();
+}
+
+function lastAssistantText(messages) {
+  for (const message of [...messages].reverse()) {
+    if (!message || typeof message !== "object") continue;
+    if (message.role === "user") break;
+    if (message.role !== "assistant") continue;
+    const text = extractText(message.content);
+    if (text) return text;
+  }
+  return "";
+}
+
+function latestUserText(messages) {
+  for (const message of [...messages].reverse()) {
+    if (!message || typeof message !== "object") continue;
+    if (message.role !== "user") continue;
+    return extractText(message.content);
+  }
+  return "";
+}
+
+function resolveProject(cwd) {
+  const explicit = process.env.AGENTMEMORY_PROJECT_NAME?.trim();
+  if (explicit) return explicit;
+  try {
+    const [top, gitDir, commonDir] = execFileSync("git", ["rev-parse", "--show-toplevel", "--git-dir", "--git-common-dir"], {
+      cwd, stdio: ["ignore", "pipe", "ignore"], timeout: 500, encoding: "utf8",
+    }).trim().split(/\r?\n/);
+    if (top) {
+      const physical = realpathSync(cwd);
+      const common = resolve(physical, commonDir || ".git");
+      return basename(gitDir && commonDir && resolve(physical, gitDir) !== common && basename(common) === ".git" ? dirname(common) : top);
+    }
+  } catch {}
+  return basename(cwd) || cwd;
+}
+
+function profileNamespace(api) {
+  const expand = (value, home) => resolve(value.replace(/^~(?=$|[/\\])/, () => home));
+  const home = expand(process.env.OPENCLAW_HOME?.trim() || homedir(), homedir());
+  const preferred = join(home, ".openclaw");
+  const legacy = join(home, ".clawdbot");
+  const fallback = process.env.OPENCLAW_STATE_DIR?.trim()
+    ? expand(process.env.OPENCLAW_STATE_DIR.trim(), home)
+    : !existsSync(preferred) && existsSync(legacy) ? legacy : preferred;
+  let canonical = resolve(api.runtime?.state?.resolveStateDir?.() || fallback);
+  try { canonical = realpathSync(canonical); } catch {}
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 24);
+}
+
+function nativeAgent(event, ctx = {}) {
+  return [ctx.agentId, event?.agentId, process.env.AGENT_ID]
+    .find((value) => typeof value === "string" && value.trim())?.trim() || "main";
+}
+
+function nativeContext(event, ctx = {}, namespace) {
+  const string = (...values) => values.find((value) => typeof value === "string" && value.trim())?.trim();
+  const cwd = string(ctx.workspaceDir, event?.workspaceDir, event?.cwd);
+  const sessionId = string(ctx.sessionId, ctx.sessionKey, event?.sessionId, event?.sessionKey);
+  if (!cwd || !sessionId) return null;
+  const agent = nativeAgent(event, ctx);
+  const agentId = "openclaw-" + createHash("sha256").update(JSON.stringify([namespace, agent])).digest("hex");
+  const scopedSession = "openclaw-" + createHash("sha256").update(JSON.stringify([namespace, agent, sessionId])).digest("hex");
+  return { cwd, project: resolveProject(cwd), sessionId: scopedSession, agentId };
+
+}
+
+function formatResults(results) {
+  if (!Array.isArray(results) || results.length === 0) return "";
+  return results
+    .slice(0, 5)
+    .map((result, index) => {
+      const obs = result?.observation ?? result ?? {};
+      const title = typeof obs.title === "string" ? obs.title.trim() : `Memory ${index + 1}`;
+      const narrative = typeof obs.narrative === "string" ? obs.narrative.trim() : "";
+      const type = typeof obs.type === "string" ? obs.type.trim() : "memory";
+      return `- ${title} (${type})${narrative ? `: ${narrative}` : ""}`;
+    })
+    .join("\n");
+}
+
+function boundedContext(block, budget) {
+  const text = `Relevant long-term memory from agentmemory (untrusted background):\n${block}`;
+  const maxBytes = budget * 4;
+  let used = 0;
+  let result = "";
+  for (const character of text) {
+    used += Buffer.byteLength(character, "utf8");
+    if (used > maxBytes) break;
+    result += character;
+  }
+  return result;
+}
+
+function usesPlaintextBearerAuth(baseUrl, secret) {
+  if (!secret) return false;
+  try {
+    const parsed = new URL(baseUrl);
+    return parsed.protocol === "http:" && !isLoopbackUrl(baseUrl);
+  } catch {
+    return false;
+  }
+}
+
+function plaintextBearerAuthMessage(baseUrl) {
+  return `agentmemory: AGENTMEMORY_SECRET is configured for plaintext HTTP to ${baseUrl}. Bearer tokens and memory payloads can be observed on the network; use HTTPS or an SSH tunnel.`;
+}
+
+export function createPlaintextBearerAuthGuard(warn, env) {
+  let warned = false;
+  return function guardPlaintextBearerAuth(baseUrl, secret) {
+    if (!usesPlaintextBearerAuth(baseUrl, secret)) return;
+    const message = plaintextBearerAuthMessage(baseUrl);
+    if ((env || process.env).AGENTMEMORY_REQUIRE_HTTPS === "1") throw new Error(message);
+    if (!warned) {
+      warned = true;
+      warn(message);
+    }
+  };
+}
+
+function usableSecret(value) {
+  const trimmed = typeof value === "string" ? value.trim() : "";
+  if (!trimmed || (trimmed.startsWith("${") && trimmed.endsWith("}"))) return "";
+  return trimmed;
+}
+
+function readAgentmemoryFile(name, home = homedir()) {
+  try {
+    return readFileSync(join(home, ".agentmemory", name), "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+function envFileSecret(home) {
+  let found = "";
+  for (const line of readAgentmemoryFile(".env", home).split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== "AGENTMEMORY_SECRET") continue;
+    let value = trimmed.slice(eq + 1).trim();
+    const quote = value[0];
+    const close = quote === '"' || quote === "'" ? value.indexOf(quote, 1) : -1;
+    if (close > 0) value = value.slice(1, close);
+    else if (value.includes(" #")) value = value.slice(0, value.indexOf(" #"));
+    found = usableSecret(value);
+  }
+  return found;
+}
+
+function isLoopbackUrl(url) {
+  try {
+    const host = new URL(url).hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    return host === "localhost" || host === "::1" || /^127(?:\.\d{1,3}){3}$/.test(host);
+  } catch {
+    return false;
+  }
+}
+
+export function resolveSecret(url, explicit, home = homedir()) {
+  const configured = usableSecret(explicit);
+  if (configured) return configured;
+  if (!isLoopbackUrl(url)) return "";
+  return envFileSecret(home) || usableSecret(readAgentmemoryFile("secret", home));
+}
+
+function createClient(cfg, api) {
+  const baseUrl = String(cfg.base_url || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  let parsed;
+  try { parsed = new URL(baseUrl); } catch {}
+  if (!parsed || !["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password || /[?#]/.test(baseUrl)) {
+    throw new Error("agentmemory: base_url must be an HTTP(S) URL without credentials, query, or fragment");
+  }
+  const timeoutMs = Number(cfg.timeout_ms || DEFAULT_TIMEOUT_MS);
+  const fallbackOnError = cfg.fallback_on_error !== false;
+  const credentialHome = homedir();
+  const secret = () => {
+    const currentUrl = String(api.pluginConfig?.base_url || process.env.AGENTMEMORY_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    if (currentUrl !== baseUrl || api.pluginConfig?.secret_env !== cfg.secret_env) {
+      throw new Error("agentmemory: endpoint or credential configuration changed; reload the plugin before using its credentials");
+    }
+    return cfg.secret_env ? usableSecret(process.env[cfg.secret_env]) : resolveSecret(baseUrl, process.env.AGENTMEMORY_SECRET, credentialHome);
+  };
+  const guardPlaintextBearerAuth = createPlaintextBearerAuthGuard(
+    (message) => api.logger.warn?.(message),
+  );
+  if (process.env.AGENTMEMORY_REQUIRE_HTTPS === "1") {
+    guardPlaintextBearerAuth(baseUrl, secret());
+  }
+
+  async function postJson(path, payload) {
+    const token = secret();
+    guardPlaintextBearerAuth(baseUrl, token);
+    const headers = { "Content-Type": "application/json" };
+    if (token) headers.Authorization = `Bearer ${token}`;
+    let failure = `agentmemory ${path} failed: network or invalid response`;
+    try {
+      const res = await fetch(`${baseUrl}${path}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(timeoutMs),
+        redirect: "error",
+      });
+      if (!res.ok) {
+        failure = `agentmemory ${path} failed: HTTP ${res.status}`;
+        throw new Error(failure);
+      }
+      return await res.json();
+    } catch (error) {
+      if (!fallbackOnError) throw new Error(failure);
+      api.logger.warn?.(failure);
+      return null;
+    }
+  }
+
+  return { postJson, baseUrl };
+}
+
+const plugin = {
+  id: "agentmemory",
+  name: "agentmemory",
+  description: "Shared cross-session memory via the local agentmemory server.",
+  configSchema,
+  register(api) {
+    const cfg = {
+      enabled: api.pluginConfig?.enabled !== false,
+      secret_env: api.pluginConfig?.secret_env,
+      base_url: api.pluginConfig?.base_url || process.env.AGENTMEMORY_URL || DEFAULT_BASE_URL,
+      token_budget: api.pluginConfig?.token_budget ?? 2000,
+      min_confidence: api.pluginConfig?.min_confidence ?? 0.5,
+      fallback_on_error: api.pluginConfig?.fallback_on_error !== false,
+      timeout_ms: api.pluginConfig?.timeout_ms ?? DEFAULT_TIMEOUT_MS,
+    };
+    if (!cfg.enabled) return;
+    if (cfg.secret_env !== undefined && (typeof cfg.secret_env !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(cfg.secret_env))) {
+      throw new Error("agentmemory: invalid secret_env");
+    }
+    const namespace = profileNamespace(api);
+    if (!Number.isInteger(cfg.token_budget) || cfg.token_budget < 0 || cfg.token_budget > 32000 ||
+        !Number.isFinite(cfg.min_confidence) || cfg.min_confidence < 0 || cfg.min_confidence > 1 ||
+        !Number.isInteger(cfg.timeout_ms) || cfg.timeout_ms < 1 || cfg.timeout_ms > 60000) {
+      throw new Error("agentmemory: invalid token_budget, min_confidence, or timeout_ms");
+    }
+    const client = createClient(cfg, api);
+
+    if (typeof api.registerMemoryCapability === "function") {
+      api.registerMemoryCapability({
+        // OpenClaw passes { availableTools: Set<string>, citationsMode? }. We
+        // don't currently branch on tool availability, but accept the params
+        // object so the signature matches MemoryPromptSectionBuilder exactly.
+        promptBuilder: (_params) => [
+          "Long-term memory provider: agentmemory (external REST service on " +
+            client.baseUrl +
+            ").",
+          "agentmemory recalls relevant prior observations before each turn via the before_prompt_build hook and captures completed turns via agent_end.",
+          "Treat recalled context as background, not authoritative — prefer current workspace state and explicit user instructions when they conflict.",
+        ],
+      });
+    }
+
+    const recall = async (event, ctx) => {
+      if (!cfg.enabled || cfg.token_budget === 0) return;
+      const prompt = typeof event?.prompt === "string" ? event.prompt.trim() : "";
+      if (!prompt) return;
+      const identity = nativeContext(event, ctx, namespace);
+      if (!identity) {
+        api.logger.warn?.("agentmemory: recall skipped because native session/workspace metadata is missing");
+        return;
+      }
+      const scope = { project: identity.project, agentId: identity.agentId,
+        sessionId: identity.sessionId, source: "openclaw" };
+      const result = await client.postJson("/agentmemory/smart-search", {
+        query: prompt, limit: 5, includeLessons: false, ...scope,
+      });
+      const ids = (Array.isArray(result?.results) ? result.results : [])
+        .filter((item) => typeof item?.obsId === "string" && Number.isFinite(item.score) && item.score >= cfg.min_confidence)
+        .slice(0, 5)
+        .map((item) => ({ obsId: item.obsId, ...(item.sessionId ? { sessionId: item.sessionId } : {}) }));
+      if (!ids.length) return;
+      const expanded = await client.postJson("/agentmemory/smart-search", { expandIds: ids, ...scope });
+      const block = formatResults(expanded?.results || []);
+      if (!block) return;
+      return { prependContext: boundedContext(block, cfg.token_budget) };
+    };
+    api.on("before_prompt_build", recall);
+
+    const startedSessions = new Map();
+    const captures = new Map();
+    const sessionAliases = new Map();
+    const capture = async (event, ctx) => {
+      if (!cfg.enabled || !event?.success || !Array.isArray(event.messages)) return;
+      const userText = latestUserText(event.messages);
+      const assistantText = lastAssistantText(event.messages);
+      if (!userText || !assistantText) return;
+      const identity = nativeContext(event, ctx, namespace);
+      if (!identity) {
+        api.logger.warn?.("agentmemory: capture skipped because native session/workspace metadata is missing");
+        return;
+      }
+      const key = JSON.stringify(identity);
+      let starting = startedSessions.get(key);
+      if (!starting) {
+        starting = client.postJson("/agentmemory/session/start", identity);
+        startedSessions.set(key, starting);
+        if (startedSessions.size > 256) startedSessions.delete(startedSessions.keys().next().value);
+      }
+      let started;
+      try {
+        started = await starting;
+      } catch (error) {
+        if (startedSessions.get(key) === starting) startedSessions.delete(key);
+        throw error;
+      }
+      if (started?.session?.id !== identity.sessionId) {
+        if (startedSessions.get(key) === starting) startedSessions.delete(key);
+        if (started) api.logger.warn?.("agentmemory: capture skipped because session startup did not confirm the requested session");
+        return;
+      }
+      const eventId = "openclaw-" + createHash("sha256").update(JSON.stringify([
+        identity, ctx?.runId || event.runId || null, event.messages.length, userText, assistantText,
+      ])).digest("hex");
+      await client.postJson("/agentmemory/observe", {
+        hookType: "post_tool_use",
+        ...identity,
+        eventId,
+        timestamp: new Date().toISOString(),
+        data: {
+          tool_name: "conversation",
+          tool_input: userText.slice(0, 1000),
+          tool_output: assistantText.slice(0, 4000),
+        },
+      });
+    };
+    api.on("agent_end", async (event, ctx) => {
+      const identity = nativeContext(event, ctx, namespace);
+      const task = capture(event, ctx);
+      if (!identity) return task;
+      const aliases = [ctx?.sessionId, ctx?.sessionKey, event?.sessionId, event?.sessionKey]
+        .filter((value) => typeof value === "string" && value.trim()).map((value) => value.trim());
+      sessionAliases.set(identity.sessionId, { aliases, nativeAgent: nativeAgent(event, ctx) });
+      if (sessionAliases.size > 1024) {
+        const idle = [...sessionAliases.keys()].find((id) => id !== identity.sessionId && !captures.has(id));
+        if (idle) sessionAliases.delete(idle);
+      }
+      const pending = captures.get(identity.sessionId) || new Set();
+      pending.add(task);
+      captures.set(identity.sessionId, pending);
+      try { return await task; }
+      finally {
+        pending.delete(task);
+        if (!pending.size) captures.delete(identity.sessionId);
+      }
+    });
+    api.on("session_end", async (event, ctx) => {
+      const candidates = [ctx?.sessionId, event?.sessionId, ctx?.sessionKey, event?.sessionKey]
+        .filter((value) => typeof value === "string" && value.trim()).map((value) => value.trim());
+      const agent = ctx?.agentId || event?.agentId ? nativeAgent(event, ctx) : undefined;
+      const matching = [...sessionAliases].filter(([, value]) =>
+        (!agent || value.nativeAgent === agent) && candidates.some((id) => value.aliases.includes(id)));
+      if (matching.length !== 1) return;
+      const sessionId = matching[0][0];
+      await Promise.allSettled([...(captures.get(sessionId) || [])]);
+      const result = await client.postJson("/agentmemory/session/end", { sessionId, final: true });
+      if (result) {
+        sessionAliases.delete(sessionId);
+        for (const key of startedSessions.keys()) {
+          if (JSON.parse(key).sessionId === sessionId) startedSessions.delete(key);
+        }
+      }
+    });
+  },
+};
+
+export default plugin;

package/integrations/openclaw/plugin.yaml

@@ -0,0 +1,26 @@
+name: agentmemory
+version: 0.9.32
+description: "Persistent cross-session memory for OpenClaw via agentmemory."
+author: "Rohit Ghumare"
+homepage: "https://github.com/rohitg00/agentmemory"
+license: Apache-2.0
+
+category: memory
+tags:
+  - memory
+  - persistence
+  - mcp
+  - context
+
+hooks:
+  - before_prompt_build
+  - agent_end
+  - session_end
+
+config:
+  enabled: true
+  base_url: http://localhost:3111
+  token_budget: 2000
+  min_confidence: 0.5
+  fallback_on_error: true
+  timeout_ms: 5000

package/integrations/openclaw/skills/agentmemory-agents/REFERENCE.md

@@ -0,0 +1,32 @@
+# agentmemory connect adapters reference
+
+Generated from `src/cli/connect/index.ts`. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing an adapter.
+
+<!-- AUTOGEN:agents START - generated by scripts/skills/generate.ts, do not edit by hand -->
+`agentmemory connect <agent>` wires the memory server into a host agent. 22 adapters:
+
+| Agent | Name | Protocol |
+| --- | --- | --- |
+| Antigravity | `antigravity` | Using MCP via ~/.gemini/config/mcp_config.json, shared by current Antigravity surfaces. Pass --with-hooks for capture through ~/.gemini/config/hooks.json. |
+| Antigravity CLI (agy) | `antigravity-cli` | Using MCP via ~/.gemini/config/mcp_config.json, shared with current Antigravity IDE versions. The `/mcp` slash command inside agy lists configured servers. Pass --with-hooks to also install the native ~/.gemini/config/hooks.json auto-capture hooks. |
+| Claude Code | `claude-code` | Using MCP. Hooks are also available, see https://github.com/rohitg00/agentmemory#claude-code-one-block-paste-it. |
+| Cline | `cline` | Using MCP via ~/.cline/data/settings/cline_mcp_settings.json (CLI), or CLINE_MCP_SETTINGS_PATH when set. VS Code users: add the same block via Cline Settings → MCP Servers → Edit JSON. |
+| Codex CLI | `codex` | Using MCP. Hooks ship via the Codex plugin; on Codex Desktop, also pass --with-hooks to install the global hooks.json workaround. |
+| Continue | `continue` | Using MCP via ~/.continue/config.yaml (preferred) or config.json (legacy, only when no yaml). |
+| GitHub Copilot CLI | `copilot-cli` | Using MCP. Install the plugin too for full hooks/skills coverage. |
+| Cursor | `cursor` | Using MCP. Lifecycle hooks ship in the Cursor plugin: Settings → Plugins → Add marketplace → this repo, then enable agentmemory. |
+| Devin CLI | `devin` | Using MCP via the user config. Devin CLI migrates mcpServers into mcp_config.json on newer builds. Pass --with-hooks for native auto-capture. |
+| Droid (Factory.ai) | `droid` | Using MCP via ~/.factory/mcp.json. The `/mcp` slash command inside droid lists configured servers. Pass --with-hooks to also install the native ~/.factory/hooks.json auto-capture hooks. |
+| DeepSeek Harness | `dsh` | Using MCP via $DSH_HOME/cordis.patch.yml (the home-level patch layer every profile loads). Tools appear as mcp__agentmemory__*. Pass --with-hooks to also wire auto-capture with the bundled native DSH plugin. |
+| Gemini CLI | `gemini-cli` | Using MCP (the only protocol Gemini CLI speaks). Memory bridge runs at :3111 underneath. |
+| Hermes Agent | `hermes` | Installs the native memory provider and bundled skills into the active Hermes profile. Credentials stay managed by Hermes. |
+| Kiro | `kiro` | Using MCP via ~/.kiro/settings/mcp.json (user-level). Workspace overrides live in .kiro/settings/mcp.json. |
+| Oh My Pi | `omp` | Installs native recall, capture and skills. Add --with-mcp for the full memory toolset. |
+| OpenClaw | `openclaw` | Installs native recall/capture and bundled skills into the active OpenClaw state directory. MCP tools are opt-in with --with-mcp. |
+| OpenCode | `opencode` | Using MCP via ~/.config/opencode/opencode.json (top-level `mcp` key). For full auto-capture, also install the bundled plugin in plugin/opencode/. |
+| OpenHuman | `openhuman` | Using native hooks (REST API at :3111). MCP not required. |
+| Pi | `pi` | Installs native recall, capture and skills. Add --with-mcp for the full memory toolset. |
+| Qwen Code | `qwen` | Using MCP via ~/.qwen/settings.json. Qwen Code's hook system can also be wired separately, see docs. |
+| Warp | `warp` | Using MCP via ~/.warp/.mcp.json. Skills auto-discover from .claude/skills/ if the Claude Code plugin is also installed. |
+| Zed | `zed` | Using MCP via ~/.config/zed/settings.json (key: context_servers). |
+<!-- AUTOGEN:agents END -->

package/integrations/openclaw/skills/agentmemory-agents/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: agentmemory-agents
+description: How agentmemory wires into host coding agents via the connect command. Use when installing agentmemory into a specific agent, when asked which agents are supported, or when a connect adapter writes the wrong config path.
+user-invocable: false
+---
+
+`agentmemory connect <agent>` merges the memory server into a host agent's config and preserves any existing servers. REST is the underlying protocol; for MCP-only hosts the adapter wires the stdio MCP bridge.
+
+## Quick start
+
+```bash
+agentmemory connect claude-code   # or cursor, codex, gemini-cli, ...
+```
+
+After wiring, restart the host or run its MCP reload (for example `/mcp` in Claude Code, or a new session after `devin mcp list` in Devin CLI) so it picks up the server. Then confirm the agent lists agentmemory's tools.
+
+Devin CLI and Devin Desktop can also install the whole plugin with `devin plugins install rohitg00/agentmemory#plugin`, which adds the skills, the MCP server, and the capture hooks in one step. Cloud Devin sessions cannot reach a local agentmemory server, so the plugin is for local sessions only.
+
+For Pi, Oh My Pi, or DeepSeek Harness, start the daemon and choose the matching command:
+
+```bash
+agentmemory connect pi --with-mcp
+agentmemory connect omp --with-mcp
+agentmemory connect dsh --with-hooks
+```
+
+Pi and OMP install native recall, capture and bundled skills; `--with-mcp` adds the tools needed by the broader workflows. Reload Pi with `/reload`, or restart OMP, then run `/agentmemory-status`. Restart DSH after enabling its bundled capture plugin. Re-run the matching connector after upgrading or moving AgentMemory so installed runtime paths stay current.
+
+Cursor's connector configures MCP. Install and enable the Cursor plugin through Settings → Plugins → Add marketplace → this repository for lifecycle capture; do not add a second global hook copy.
+
+## Workflow
+
+1. Detect the calling agent. If unknown, ask which host to configure before changing files.
+2. Run `agentmemory connect <name>` using a name from the table in REFERENCE.md.
+3. Read the command result: an adapter that prints manual setup instructions has not completed installation. Restart the configured host, inspect its actual tool inventory, and perform an authorized save/recall check. A native memory provider and an MCP connection are separate surfaces (see [TROUBLESHOOTING.md](TROUBLESHOOTING.md)).
+
+## Notes
+
+- Hermes, OpenClaw, Pi and OMP connectors bundle skills. For a separate skills installation, use `npx skills@1.7.1 add rohitg00/agentmemory --agent hermes-agent --skill '*'` or `--agent openclaw`. Choose the intended host; add `--global` only for a user-wide installation. Avoid duplicate skill installations when a native package already bundles them. Verify skill discovery and read a skill's local support file in that host.
+- Native Windows supports `agentmemory connect copilot-cli`. Other automated connectors require macOS, Linux or a host running in the same WSL2 environment; use the host's manual setup instructions otherwise.
+
+## See also
+
+- agentmemory-mcp-tools, agentmemory-rest-api, agentmemory-hooks.
+
+## Reference
+
+The full adapter list with display names and protocol notes lives in REFERENCE.md, generated from `src/cli/connect/`.

package/integrations/openclaw/skills/agentmemory-agents/TROUBLESHOOTING.md

@@ -0,0 +1,70 @@
+<!-- AUTOGEN:troubleshooting START - generated by scripts/skills/generate.ts, do not edit by hand -->
+# Troubleshooting agentmemory skills
+
+Recovery steps for separately installed skills. This document is generated into
+each skill directory so native skill readers can open it without parent traversal.
+
+## "MCP tool not available"
+
+Missing tools can mean a stopped MCP process, a disconnected daemon, or an
+explicitly reduced tool surface. Walk these in order:
+
+1. Identify the host. In Claude Code, inspect `/plugin list` and `/mcp`.
+   In Hermes, inspect the configured memory provider and `mcp_servers` separately.
+   In OpenClaw, validate the host configuration and inspect its MCP servers and
+   native plugins separately. In Pi or OMP, inspect `/agentmemory-status` and the
+   MCP inventory separately; native save/search does not prove the broader tools
+   are connected. Do not run another host's setup commands.
+2. Restart or reload the affected host connection after configuration changes.
+3. Inspect the connected tool inventory. Hermes may namespace MCP tools; invoke
+   the actual advertised names and schemas. A native memory provider is not
+   proof that every MCP tool or shared skill is available.
+4. Check `agentmemory status` and the daemon's `AGENTMEMORY_TOOLS` setting.
+   Codex's bundled bridge lists the daemon's enabled tools. The standalone shim
+   used by other hosts can fall back to seven basic tools with a separate store.
+   Do not claim full daemon functionality based on those seven tools.
+5. If `agentmemory connect codex` and the Codex plugin are both enabled, choose
+   one MCP connection. Check `/hooks` before adding global hook fallbacks.
+
+Hermes, OpenClaw, Pi and OMP connector installations bundle skills; other hosts
+may install them separately. Check the host's skill inventory and open this file
+from the installed skill directory. Test automatic capture with a real turn and
+a recorded observation; tool connectivity alone does not establish lifecycle
+capture.
+
+An outage or timeout is not an empty search result. Report the failure. A write
+may have committed before the response was lost; inspect state before retrying.
+
+## REST fallback
+
+When the MCP tools stay unavailable but the daemon is running, call the REST
+API directly:
+
+1. Set `AGENTMEMORY_URL` to the daemon base URL (default `http://localhost:3111`).
+2. The REST API requires a bearer credential by default. Use the host's explicit
+   `AGENTMEMORY_SECRET`; for loopback URLs only, fall back to the secret in
+   `~/.agentmemory/.env` and then `~/.agentmemory/secret`. Load the value locally
+   without displaying it. Never send a local-file secret to a remote URL.
+   If `AGENTMEMORY_CREDENTIAL_MODE=explicit`, require the explicit host credential
+   and do not read local credential files.
+   Authenticated REST fallback requests require HTTPS for non-loopback
+   URLs; HTTP is allowed for loopback URLs (`localhost`, `127.0.0.0/8`, or `[::1]`).
+   Reject redirects on authenticated requests. Do not print or save the secret.
+
+Endpoint map by skill:
+
+| Skill           | REST call                                                        |
+| --------------- | --------------------------------------------------------------- |
+| remember        | `POST /agentmemory/remember`                                     |
+| recall          | `POST /agentmemory/smart-search`                                 |
+| recap           | `GET /agentmemory/sessions` + `POST /agentmemory/smart-search`   |
+| handoff         | `GET /agentmemory/sessions` + `POST /agentmemory/smart-search`   |
+| session-history | `GET /agentmemory/sessions`                                      |
+| commit-context  | `GET /agentmemory/session/by-commit?sha=<sha>`                   |
+| commit-history  | `GET /agentmemory/commits` (URL-encode every query param)       |
+
+The MCP host reads the plugin MCP configuration. Restart the daemon after
+changing its configuration, then restart or reconnect the host MCP process after
+changing its URL or explicit secret. The local bridge reads the credential files
+for each request; it does not inherit other daemon `.env` settings.
+<!-- AUTOGEN:troubleshooting END -->

package/integrations/openclaw/skills/agentmemory-architecture/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: agentmemory-architecture
+description: How agentmemory is built, the iii engine primitives it runs on, its storage model, ports, and the viewer. Use when reasoning about how memory is stored or retrieved end to end, when extending the system, or when answering how agentmemory works under the hood.
+user-invocable: false
+---
+
+agentmemory is a memory server for coding agents. It runs locally, captures observations, indexes them for hybrid retrieval, and serves them back over REST and MCP. Worker Compose runs the pinned iii engine with AgentMemory and the registry `state` and `http` workers. The state worker uses a file-backed KV store by default, with Redis available by configuration; it is not SQLite.
+
+## iii primitives
+
+Everything is a function, a trigger, or worker state on the iii engine. There is no separate plugin system; the worker registers functions (`mem::*`) and HTTP triggers (`api::*`) and the engine routes calls. agentmemory does not bypass iii; new capability is a new function plus a trigger.
+
+## Retrieval model
+
+Recall combines BM25 keyword search with configured vector similarity and graph expansion. A clean installation has no embedding provider and uses BM25 without an API key. Set `EMBEDDING_PROVIDER=local` to enable on-device embeddings, which download a model once. A remote embedding provider runs only when `EMBEDDING_PROVIDER` names it. LLM summaries, consolidation and reflection run only when `AGENTMEMORY_LLM_PROVIDER` selects a provider or `AGENTMEMORY_ALLOW_AGENT_SDK=true` turns on the Claude Agent SDK fallback; a key in the environment alone does not turn them on. Per-observation LLM compression also needs `AGENTMEMORY_AUTO_COMPRESS=true`.
+
+## Data boundary
+
+Captured prompts, tool inputs and outputs, and memories stay in the local store. They leave the machine only through options the user turns on: a selected LLM provider, the Agent SDK fallback (`AGENTMEMORY_ALLOW_AGENT_SDK=true`), a remote embedding provider, a Redis state backend, or mesh sync to peer servers the user registers.
+
+## Storage and lifecycle
+
+Memories carry content, concepts, files, importance, and timestamps, grouped into sessions and optionally linked to commits. A lifecycle of capture, compress, consolidate, and forget keeps the store useful over time rather than letting it grow unbounded.
+
+## Ports
+
+REST defaults to port `3111`, the viewer to `3113`, and the internal engine WebSocket to `49134`. Use `--port <N>` or `--instance <N>` to select another local runtime.
+
+## Viewer
+
+A real-time web viewer at `http://localhost:3113` shows memory building as sessions run, with authenticated SSE updates over the REST port. Useful for demos and for confirming capture is working.
+
+## See also
+
+- agentmemory-mcp-tools and agentmemory-rest-api for the surfaces.
+- agentmemory-hooks for automatic capture.
+- agentmemory-config for ports and feature flags.