human-like-mem-openclaw-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Personal Flow Team
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,207 @@
+# Human-Like Memory Plugin for OpenClaw
+
+一个用于 OpenClaw 的长期记忆插件，自动在对话前召回相关记忆，并在对话后持久化新记忆。
+
+## 功能特性
+
+- **自动记忆召回**: 在 Agent 开始前自动检索与当前对话相关的历史记忆
+- **自动记忆存储**: 在对话结束后自动将对话保存为新的记忆
+- **全局/会话记忆**: 支持跨会话的全局记忆检索或仅当前会话的记忆
+- **灵活配置**: 支持通过环境变量或配置文件自定义所有参数
+- **异步模式**: 支持异步模式，不阻塞对话流程
+
+## 安装
+
+### 方式 A: 本地路径安装 (推荐，适合离线环境)
+
+1. 将插件文件夹复制到 OpenClaw 扩展目录：
+
+```bash
+# 复制到默认扩展目录
+cp -r human-like-mem-openclaw-plugin ~/.openclaw/extensions/
+
+# 或者放到任意位置，然后配置路径
+```
+
+2. 编辑 `~/.openclaw/openclaw.json`：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "human-like-mem-openclaw-plugin": { "enabled": true }
+    },
+    "load": {
+      "paths": ["~/.openclaw/extensions/human-like-mem-openclaw-plugin"]
+    }
+  }
+}
+```
+
+### 方式 B: 从 npm 安装
+
+```bash
+npm install human-like-mem-openclaw-plugin
+# 或
+yarn add human-like-mem-openclaw-plugin
+# 或
+pnpm add human-like-mem-openclaw-plugin
+```
+
+### 方式 C: 从 Git 仓库安装
+
+```bash
+npm install git+https://gitlab.ttyuyin.com/personalization_group/human-like-mem-openclaw-plugin.git
+```
+
+### 方式 D: 从 tarball 安装 (离线环境)
+
+```bash
+# 在有网络的机器上打包
+npm pack
+
+# 将 .tgz 文件拷贝到目标机器，然后安装
+npm install ./human-like-mem-openclaw-plugin-0.1.0.tgz
+```
+
+## 配置
+
+### 1. 启用插件
+
+编辑 `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "human-like-mem-openclaw-plugin": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+### 2. 配置环境变量
+
+```bash
+# 必需配置
+export MEMORY_SYSTEM_TOKEN="your-system-token"  # 系统认证令牌
+export MEMORY_BASE_URL="https://your-memory-api.example.com"  # API 地址
+
+# 可选配置
+export MEMORY_USER_ID="your-user-id"  # 用户标识 (默认: openclaw-user)
+export MEMORY_AGENT_ID="your-agent-id"  # Agent 标识 (默认: openclaw-agent)
+export MEMORY_RECALL_ENABLED="true"  # 启用记忆召回 (默认: true)
+export MEMORY_ADD_ENABLED="true"  # 启用记忆存储 (默认: true)
+export MEMORY_RECALL_GLOBAL="true"  # 全局记忆搜索 (默认: true)
+export MEMORY_LIMIT_NUMBER="6"  # 召回记忆数量 (默认: 6)
+export MEMORY_MIN_SCORE="0.1"  # 最低相关性分数 (默认: 0.1)
+export MEMORY_SCENARIO=""  # 记忆场景过滤
+```
+
+### 3. 完整配置参数
+
+| 参数 | 环境变量 | 默认值 | 说明 |
+|------|----------|--------|------|
+| `baseUrl` | `MEMORY_BASE_URL` | - | Memory 服务 API 地址 |
+| `systemToken` | `MEMORY_SYSTEM_TOKEN` | - | 系统认证令牌 (必需) |
+| `userId` | `MEMORY_USER_ID` | `openclaw-user` | 用户标识 |
+| `agentId` | `MEMORY_AGENT_ID` | `openclaw-agent` | Agent 标识 |
+| `recallEnabled` | `MEMORY_RECALL_ENABLED` | `true` | 是否启用记忆召回 |
+| `addEnabled` | `MEMORY_ADD_ENABLED` | `true` | 是否启用记忆存储 |
+| `recallGlobal` | `MEMORY_RECALL_GLOBAL` | `true` | 是否全局搜索记忆 |
+| `memoryLimitNumber` | `MEMORY_LIMIT_NUMBER` | `6` | 召回记忆的最大数量 |
+| `minScore` | `MEMORY_MIN_SCORE` | `0.1` | 最低相关性分数阈值 |
+| `scenario` | `MEMORY_SCENARIO` | `""` | 记忆场景过滤 |
+| `captureStrategy` | `MEMORY_CAPTURE_STRATEGY` | `last_turn` | 消息捕获策略 |
+| `maxMessageChars` | `MEMORY_MAX_MESSAGE_CHARS` | `20000` | 单条消息最大字符数 |
+| `asyncMode` | `MEMORY_ASYNC_MODE` | `true` | 异步模式 |
+| `timeoutMs` | `MEMORY_TIMEOUT_MS` | `5000` | 请求超时时间 (ms) |
+| `retries` | `MEMORY_RETRIES` | `1` | 重试次数 |
+| `throttleMs` | `MEMORY_THROTTLE_MS` | `0` | 节流间隔 (ms) |
+| `addMemoryList` | `MEMORY_ADD_LIST` | `["stream_v2"]` | 要添加的记忆类型 |
+
+## 工作流程
+
+### 记忆召回 (before_agent_start)
+
+1. 用户发送消息
+2. 插件使用消息内容作为查询，调用 `/memory/v2/memory-stream-unified-retrieval`
+3. 检索到的相关记忆被格式化并注入到 Agent 的上下文中
+4. Agent 开始处理用户请求
+
+### 记忆存储 (agent_end)
+
+1. Agent 完成响应
+2. 插件提取最后一轮对话 (或完整会话)
+3. 调用 `/memory/v2/memory-add` 保存对话
+4. 对话被总结并存储为情景记忆
+
+## API 接口
+
+本插件调用以下 Memory 服务 API:
+
+### 记忆检索
+
+```
+POST /memory/v2/memory-stream-unified-retrieval
+Header: system-token: <your-token>
+
+{
+  "query": "用户的问题",
+  "user_id": "user-123",
+  "agent_id": "agent-456",
+  "limit": 6,
+  "min_score": 0.1,
+  "is_global_memory": true
+}
+```
+
+### 记忆添加
+
+```
+POST /memory/v2/memory-add
+Header: system-token: <your-token>
+
+{
+  "messages": [
+    {"role": "user", "content": "..."},
+    {"role": "assistant", "content": "..."}
+  ],
+  "session_id": "conversation-123",
+  "user_id": "user-123",
+  "agent_id": "agent-456",
+  "add_memory_list": ["stream_v2"]
+}
+```
+
+## 内网/公网部署
+
+### 内网用户
+
+直接配置内网 API 地址:
+
+```bash
+export MEMORY_BASE_URL="http://memory-server.internal:9008"
+```
+
+### 公网用户
+
+配置公网网关地址:
+
+```bash
+export MEMORY_BASE_URL="https://memory-api.your-domain.com"
+```
+
+## 许可证
+
+Apache-2.0
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request!
+
+## 联系
+
+- 作者: Personal Flow Team

package/README_ZH.md

@@ -0,0 +1,152 @@
+# Human-Like Memory Plugin for OpenClaw
+
+[English](README.md) | 中文
+
+一个用于 OpenClaw 的长期记忆插件，自动在对话前召回相关记忆，并在对话后持久化新记忆。
+
+## 功能特性
+
+- 🧠 **自动记忆召回**: 在 Agent 开始前自动检索与当前对话相关的历史记忆
+- 💾 **自动记忆存储**: 在对话结束后自动将对话保存为新的记忆
+- 🌍 **全局/会话记忆**: 支持跨会话的全局记忆检索或仅当前会话的记忆
+- ⚙️ **灵活配置**: 支持通过环境变量或配置文件自定义所有参数
+- ⚡ **异步模式**: 支持异步模式，不阻塞对话流程
+
+## 快速开始
+
+### 1. 安装插件
+
+**方式 A: 本地路径安装 (推荐，适合离线环境)**
+
+```bash
+# 将插件文件夹复制到 OpenClaw 扩展目录
+cp -r human-like-mem-openclaw-plugin ~/.openclaw/extensions/
+```
+
+**方式 B: 从 Git 仓库安装**
+
+```bash
+npm install git+https://gitlab.ttyuyin.com/personalization_group/human-like-mem-openclaw-plugin.git
+```
+
+**方式 C: 从 tarball 安装 (离线环境)**
+
+```bash
+# 将 .tgz 文件拷贝到目标机器
+npm install ./human-like-mem-openclaw-plugin-0.1.0.tgz
+```
+
+### 2. 配置环境变量
+
+```bash
+# 添加到 ~/.zshrc 或 ~/.bashrc
+export MEMORY_SYSTEM_TOKEN="your-system-token"
+export MEMORY_BASE_URL="https://your-memory-api.example.com"
+export MEMORY_USER_ID="your-user-id"
+
+source ~/.zshrc
+```
+
+### 3. 启用插件
+
+编辑 `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "human-like-mem-openclaw-plugin": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+### 4. 重启 OpenClaw
+
+```bash
+openclaw gateway restart
+```
+
+## 工作原理
+
+```
+用户输入
+    │
+    ▼
+┌─────────────────────────────────────┐
+│  before_agent_start                  │
+│  - 使用用户输入检索相关记忆           │
+│  - 将记忆注入到 Agent 上下文          │
+└─────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────┐
+│  Agent 处理                          │
+│  - Agent 可以看到历史记忆            │
+│  - Agent 生成响应                    │
+└─────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────┐
+│  agent_end                           │
+│  - 提取本轮对话                      │
+│  - 异步保存到记忆服务                 │
+└─────────────────────────────────────┘
+    │
+    ▼
+用户收到响应
+```
+
+## 配置说明
+
+### 必需配置
+
+| 参数 | 环境变量 | 说明 |
+|------|----------|------|
+| `systemToken` | `MEMORY_SYSTEM_TOKEN` | 系统认证令牌，用于 API 鉴权 |
+| `baseUrl` | `MEMORY_BASE_URL` | Memory 服务的 API 地址 |
+
+### 可选配置
+
+| 参数 | 环境变量 | 默认值 | 说明 |
+|------|----------|--------|------|
+| `userId` | `MEMORY_USER_ID` | `openclaw-user` | 用户标识 |
+| `agentId` | `MEMORY_AGENT_ID` | `openclaw-agent` | Agent 标识 |
+| `recallEnabled` | `MEMORY_RECALL_ENABLED` | `true` | 是否启用记忆召回 |
+| `addEnabled` | `MEMORY_ADD_ENABLED` | `true` | 是否启用记忆存储 |
+| `recallGlobal` | `MEMORY_RECALL_GLOBAL` | `true` | 是否全局搜索记忆 |
+| `memoryLimitNumber` | `MEMORY_LIMIT_NUMBER` | `6` | 召回记忆的最大数量 |
+| `minScore` | `MEMORY_MIN_SCORE` | `0.1` | 最低相关性分数 (0-1) |
+| `captureStrategy` | `MEMORY_CAPTURE_STRATEGY` | `last_turn` | `last_turn` 或 `full_session` |
+
+## 常见问题
+
+### Q: 如何获取 System Token?
+
+A: 请联系管理员获取系统令牌，或在 Memory 服务管理后台创建。
+
+### Q: 为什么记忆没有被召回?
+
+A: 检查以下几点:
+1. 确认 `MEMORY_RECALL_ENABLED` 为 `true`
+2. 确认 `MEMORY_SYSTEM_TOKEN` 已正确配置
+3. 确认 Memory 服务可访问
+4. 检查 `min_score` 设置是否过高
+
+### Q: 如何只保存记忆不召回?
+
+A: 设置 `MEMORY_RECALL_ENABLED=false`
+
+### Q: 如何调试插件?
+
+A: 查看 OpenClaw 的日志输出，插件会记录详细的调试信息。
+
+## 许可证
+
+Apache-2.0
+
+## 联系我们
+
+- 作者: Personal Flow Team

package/index.js

@@ -0,0 +1,435 @@
+/**
+ * AI Social Memory Plugin for OpenClaw
+ *
+ * A lifecycle plugin that integrates long-term memory capabilities.
+ * Automatically recalls relevant memories before agent execution
+ * and persists conversations afterward.
+ *
+ * @author Personal Flow Team <jianghaibo@52tt.com>
+ * @license Apache-2.0
+ */
+
+const USER_QUERY_MARKER = "--- User Query ---";
+
+// Session-level conversation counters for unique IDs
+const conversationCounters = new Map();
+
+// Throttle state for rate limiting
+let lastAddTime = 0;
+
+/**
+ * Display warning when system token is not configured
+ */
+function warnMissingSystemToken(log, context) {
+  const msg = `
+╔════════════════════════════════════════════════════════════════════════════╗
+║  ⚠️  Memory Plugin: MEMORY_SYSTEM_TOKEN not configured                      ║
+║                                                                              ║
+║  Please set your system token:                                               ║
+║                                                                              ║
+║  Bash/Zsh:                                                                   ║
+║    echo 'export MEMORY_SYSTEM_TOKEN="your-token"' >> ~/.zshrc                ║
+║    source ~/.zshrc                                                           ║
+║                                                                              ║
+║  PowerShell:                                                                 ║
+║    [Environment]::SetEnvironmentVariable("MEMORY_SYSTEM_TOKEN", "your-token",║
+║      "User")                                                                 ║
+║                                                                              ║
+║  Contact your administrator to obtain a system token.                        ║
+╚════════════════════════════════════════════════════════════════════════════╝
+`;
+  if (log?.warn) {
+    log.warn(msg);
+  } else {
+    console.warn(msg);
+  }
+}
+
+/**
+ * Strip prepended prompt markers from message content
+ */
+function stripPrependedPrompt(content) {
+  if (!content) return content;
+  const markerIndex = content.indexOf(USER_QUERY_MARKER);
+  if (markerIndex !== -1) {
+    return content.substring(markerIndex + USER_QUERY_MARKER.length).trim();
+  }
+  return content;
+}
+
+/**
+ * Get counter suffix for conversation ID (e.g., "#1", "#2")
+ */
+function getCounterSuffix(sessionKey) {
+  const count = conversationCounters.get(sessionKey) || 0;
+  return count > 0 ? `#${count}` : "";
+}
+
+/**
+ * Increment conversation counter for a session
+ */
+function bumpConversationCounter(sessionKey) {
+  const current = conversationCounters.get(sessionKey) || 0;
+  conversationCounters.set(sessionKey, current + 1);
+}
+
+/**
+ * Generate a unique conversation ID
+ */
+function resolveConversationId(cfg, ctx) {
+  const base = ctx.conversationId || ctx.sessionId || `session-${Date.now()}`;
+  const prefix = cfg.conversationIdPrefix || "";
+  const suffix = cfg.conversationIdSuffix || "";
+  const sessionKey = `${prefix}${base}${suffix}`;
+  const counterSuffix = getCounterSuffix(sessionKey);
+  return `${sessionKey}${counterSuffix}`;
+}
+
+/**
+ * Truncate text to specified maximum length
+ */
+function truncate(text, maxLen) {
+  if (!text || text.length <= maxLen) return text;
+  return text.substring(0, maxLen - 3) + "...";
+}
+
+/**
+ * Build payload for memory retrieval API
+ */
+function buildRetrievalPayload(cfg, prompt, ctx) {
+  const payload = {
+    query: prompt,
+    user_id: cfg.userId || ctx.userId || "openclaw-user",
+    agent_id: cfg.agentId || ctx.agentId || "openclaw-agent",
+    limit: cfg.memoryLimitNumber || 6,
+    min_score: cfg.minScore || 0.1,
+    scenarios: cfg.scenario ? [cfg.scenario] : [],
+    user_ids: [cfg.userId || ctx.userId || "openclaw-user"],
+    agent_ids: [cfg.agentId || ctx.agentId || "openclaw-agent"],
+    is_global_memory: cfg.recallGlobal !== false,
+  };
+
+  // Add session_id for non-global search
+  if (!payload.is_global_memory && ctx.sessionId) {
+    payload.session_id = ctx.sessionId;
+  }
+
+  return payload;
+}
+
+/**
+ * Build payload for memory add API
+ */
+function buildAddMemoryPayload(cfg, messages, ctx) {
+  const conversationId = resolveConversationId(cfg, ctx);
+
+  return {
+    messages: messages.map(m => ({
+      role: m.role,
+      content: truncate(m.content, cfg.maxMessageChars || 20000),
+      created_time: m.createdTime || Date.now(),
+    })),
+    session_id: conversationId,
+    user_id: cfg.userId || ctx.userId || "openclaw-user",
+    agent_id: cfg.agentId || ctx.agentId || "openclaw-agent",
+    user_ids: [cfg.userId || ctx.userId || "openclaw-user"],
+    agent_ids: [cfg.agentId || ctx.agentId || "openclaw-agent"],
+    add_memory_list: cfg.addMemoryList || ["stream_v2"],
+    scenario: cfg.scenario || "",
+    session_end: false,
+    episodic_memory_type: cfg.recallGlobal !== false ? "global" : "specific",
+  };
+}
+
+/**
+ * Extract only the last user-assistant exchange
+ */
+function pickLastTurnMessages(messages, cfg) {
+  if (!messages || messages.length === 0) return [];
+
+  const result = [];
+
+  // Find last user message
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === "user") {
+      result.unshift({
+        role: "user",
+        content: stripPrependedPrompt(messages[i].content),
+        createdTime: messages[i].createdTime,
+      });
+      break;
+    }
+  }
+
+  // Find last assistant message
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === "assistant") {
+      result.push({
+        role: "assistant",
+        content: messages[i].content,
+        createdTime: messages[i].createdTime,
+      });
+      break;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Process full session messages
+ */
+function pickFullSessionMessages(messages, cfg) {
+  if (!messages || messages.length === 0) return [];
+
+  return messages.map(m => ({
+    role: m.role,
+    content: m.role === "user" ? stripPrependedPrompt(m.content) : m.content,
+    createdTime: m.createdTime,
+  }));
+}
+
+/**
+ * Make HTTP request with retry logic
+ */
+async function httpRequest(url, options, cfg, log) {
+  const timeout = cfg.timeoutMs || 5000;
+  const retries = cfg.retries || 1;
+
+  let lastError;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`HTTP ${response.status}: ${errorText}`);
+      }
+
+      return await response.json();
+    } catch (error) {
+      lastError = error;
+      if (log?.debug) {
+        log.debug(`Request attempt ${attempt + 1} failed: ${error.message}`);
+      }
+
+      // Don't retry on abort (timeout)
+      if (error.name === 'AbortError') break;
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Retrieve memories from the API
+ */
+async function retrievalMemory(prompt, cfg, ctx, log) {
+  const baseUrl = cfg.baseUrl || process.env.MEMORY_BASE_URL;
+  const systemToken = cfg.systemToken || process.env.MEMORY_SYSTEM_TOKEN;
+
+  if (!systemToken) {
+    warnMissingSystemToken(log, ctx);
+    return [];
+  }
+
+  const url = `${baseUrl}/memory/v2/memory-stream-unified-retrieval`;
+  const payload = buildRetrievalPayload(cfg, prompt, ctx);
+
+  try {
+    const result = await httpRequest(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "system-token": systemToken,
+        "x-request-id": ctx.requestId || `openclaw-${Date.now()}`,
+      },
+      body: JSON.stringify(payload),
+    }, cfg, log);
+
+    if (log?.debug) {
+      log.debug(`Retrieved ${result.streams?.length || 0} memories`);
+    }
+
+    return result.streams || [];
+  } catch (error) {
+    if (log?.warn) {
+      log.warn(`Memory retrieval failed: ${error.message}`);
+    }
+    return [];
+  }
+}
+
+/**
+ * Add memories to the API
+ */
+async function addMemory(messages, cfg, ctx, log) {
+  const baseUrl = cfg.baseUrl || process.env.MEMORY_BASE_URL;
+  const systemToken = cfg.systemToken || process.env.MEMORY_SYSTEM_TOKEN;
+
+  if (!systemToken) {
+    return;
+  }
+
+  // Throttle check
+  const throttleMs = cfg.throttleMs || 0;
+  if (throttleMs > 0) {
+    const now = Date.now();
+    if (now - lastAddTime < throttleMs) {
+      if (log?.debug) {
+        log.debug(`Memory add throttled, skipping`);
+      }
+      return;
+    }
+    lastAddTime = now;
+  }
+
+  const url = `${baseUrl}/memory/v2/memory-add`;
+  const payload = buildAddMemoryPayload(cfg, messages, ctx);
+
+  try {
+    const result = await httpRequest(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "system-token": systemToken,
+        "x-request-id": ctx.requestId || `openclaw-${Date.now()}`,
+      },
+      body: JSON.stringify(payload),
+    }, cfg, log);
+
+    if (log?.debug) {
+      log.debug(`Memory added successfully: ${result.streams?.length || 0} streams`);
+    }
+
+    return result;
+  } catch (error) {
+    if (log?.warn) {
+      log.warn(`Memory add failed: ${error.message}`);
+    }
+  }
+}
+
+/**
+ * Format memories for injection into context
+ */
+function formatMemoriesForContext(memories) {
+  if (!memories || memories.length === 0) return "";
+
+  const lines = memories.map((m, i) => {
+    const date = m.stream_date || m.date || "";
+    const desc = m.description || m.event || "";
+    const score = m.score ? ` (relevance: ${(m.score * 100).toFixed(1)}%)` : "";
+    return `${i + 1}. [${date}] ${desc}${score}`;
+  });
+
+  return `## Relevant Memories\n\n${lines.join("\n")}\n\n${USER_QUERY_MARKER}\n`;
+}
+
+/**
+ * Main plugin export
+ */
+export default function(config) {
+  const cfg = {
+    baseUrl: config.baseUrl || process.env.MEMORY_BASE_URL || "https://memory-api.example.com",
+    systemToken: config.systemToken || process.env.MEMORY_SYSTEM_TOKEN,
+    userId: config.userId || process.env.MEMORY_USER_ID || "openclaw-user",
+    agentId: config.agentId || process.env.MEMORY_AGENT_ID || "openclaw-agent",
+    recallEnabled: config.recallEnabled !== false,
+    addEnabled: config.addEnabled !== false,
+    recallGlobal: config.recallGlobal !== false,
+    memoryLimitNumber: config.memoryLimitNumber || 6,
+    minScore: config.minScore || 0.1,
+    scenario: config.scenario || "",
+    conversationIdPrefix: config.conversationIdPrefix || "",
+    conversationIdSuffix: config.conversationIdSuffix || "",
+    captureStrategy: config.captureStrategy || "last_turn",
+    maxMessageChars: config.maxMessageChars || 20000,
+    asyncMode: config.asyncMode !== false,
+    timeoutMs: config.timeoutMs || 5000,
+    retries: config.retries ?? 1,
+    throttleMs: config.throttleMs || 0,
+    addMemoryList: config.addMemoryList || ["stream_v2"],
+  };
+
+  return {
+    hooks: {
+      /**
+       * Before agent start: Recall relevant memories
+       */
+      "before_agent_start": async (ctx) => {
+        if (!cfg.recallEnabled) return;
+
+        const log = ctx.log;
+        const prompt = ctx.prompt || "";
+
+        if (!prompt.trim()) {
+          if (log?.debug) {
+            log.debug("Empty prompt, skipping memory recall");
+          }
+          return;
+        }
+
+        const memories = await retrievalMemory(prompt, cfg, ctx, log);
+
+        if (memories.length > 0) {
+          ctx.prependPrompt = formatMemoriesForContext(memories);
+
+          if (log?.info) {
+            log.info(`Injected ${memories.length} memories into context`);
+          }
+        }
+      },
+
+      /**
+       * After agent end: Store conversation to memory
+       */
+      "agent_end": async (ctx) => {
+        if (!cfg.addEnabled) return;
+
+        const log = ctx.log;
+        const messages = ctx.messages || [];
+
+        if (messages.length === 0) {
+          if (log?.debug) {
+            log.debug("No messages to save");
+          }
+          return;
+        }
+
+        // Pick messages based on capture strategy
+        const messagesToSave = cfg.captureStrategy === "full_session"
+          ? pickFullSessionMessages(messages, cfg)
+          : pickLastTurnMessages(messages, cfg);
+
+        if (messagesToSave.length === 0) {
+          if (log?.debug) {
+            log.debug("No valid messages to save after processing");
+          }
+          return;
+        }
+
+        // Run async or sync based on config
+        if (cfg.asyncMode) {
+          // Fire and forget
+          addMemory(messagesToSave, cfg, ctx, log).catch(err => {
+            if (log?.warn) {
+              log.warn(`Async memory add failed: ${err.message}`);
+            }
+          });
+        } else {
+          await addMemory(messagesToSave, cfg, ctx, log);
+        }
+      },
+    },
+  };
+}

package/openclaw.plugin.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://openclaw.io/schemas/plugin.json",
+  "id": "human-like-mem-openclaw-plugin",
+  "name": "AI Social Memory Plugin",
+  "description": "Long-term memory plugin for OpenClaw. Automatically recalls relevant memories before conversations and persists new memories after interactions.",
+  "version": "0.1.0",
+  "kind": "lifecycle",
+  "main": "./index.js",
+  "author": {
+    "name": "hanlaomo"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/personalization-group/memory-openclaw-plugin"
+  },
+  "license": "Apache-2.0",
+  "keywords": ["memory", "long-term-memory", "ai-social", "recall", "openclaw"],
+
+  "config": {
+    "baseUrl": {
+      "type": "string",
+      "description": "Memory service API base URL",
+      "default": "https://memory-api.example.com",
+      "env": "MEMORY_BASE_URL"
+    },
+    "systemToken": {
+      "type": "string",
+      "description": "System token for authentication (required)",
+      "env": "MEMORY_SYSTEM_TOKEN",
+      "required": true
+    },
+    "userId": {
+      "type": "string",
+      "description": "User identifier",
+      "default": "openclaw-user",
+      "env": "MEMORY_USER_ID"
+    },
+    "agentId": {
+      "type": "string",
+      "description": "Agent identifier",
+      "default": "openclaw-agent",
+      "env": "MEMORY_AGENT_ID"
+    },
+    "recallEnabled": {
+      "type": "boolean",
+      "description": "Enable memory recall before agent start",
+      "default": true,
+      "env": "MEMORY_RECALL_ENABLED"
+    },
+    "addEnabled": {
+      "type": "boolean",
+      "description": "Enable memory storage after conversation",
+      "default": true,
+      "env": "MEMORY_ADD_ENABLED"
+    },
+    "recallGlobal": {
+      "type": "boolean",
+      "description": "Search across all conversations (true) or current session only (false)",
+      "default": true,
+      "env": "MEMORY_RECALL_GLOBAL"
+    },
+    "memoryLimitNumber": {
+      "type": "number",
+      "description": "Maximum number of memories to retrieve",
+      "default": 6,
+      "env": "MEMORY_LIMIT_NUMBER"
+    },
+    "minScore": {
+      "type": "number",
+      "description": "Minimum relevance score for retrieved memories (0.0-1.0)",
+      "default": 0.1,
+      "env": "MEMORY_MIN_SCORE"
+    },
+    "scenario": {
+      "type": "string",
+      "description": "Memory scenario/category filter",
+      "default": "",
+      "env": "MEMORY_SCENARIO"
+    },
+    "conversationIdPrefix": {
+      "type": "string",
+      "description": "Prefix for conversation ID",
+      "default": "",
+      "env": "MEMORY_CONVERSATION_PREFIX"
+    },
+    "conversationIdSuffix": {
+      "type": "string",
+      "description": "Suffix for conversation ID",
+      "default": "",
+      "env": "MEMORY_CONVERSATION_SUFFIX"
+    },
+    "captureStrategy": {
+      "type": "string",
+      "description": "Message capture strategy: 'last_turn' or 'full_session'",
+      "default": "last_turn",
+      "env": "MEMORY_CAPTURE_STRATEGY"
+    },
+    "maxMessageChars": {
+      "type": "number",
+      "description": "Maximum characters per message",
+      "default": 20000,
+      "env": "MEMORY_MAX_MESSAGE_CHARS"
+    },
+    "asyncMode": {
+      "type": "boolean",
+      "description": "Run memory operations asynchronously",
+      "default": true,
+      "env": "MEMORY_ASYNC_MODE"
+    },
+    "timeoutMs": {
+      "type": "number",
+      "description": "API request timeout in milliseconds",
+      "default": 5000,
+      "env": "MEMORY_TIMEOUT_MS"
+    },
+    "retries": {
+      "type": "number",
+      "description": "Number of retry attempts on failure",
+      "default": 1,
+      "env": "MEMORY_RETRIES"
+    },
+    "throttleMs": {
+      "type": "number",
+      "description": "Throttle interval for memory add operations",
+      "default": 0,
+      "env": "MEMORY_THROTTLE_MS"
+    },
+    "addMemoryList": {
+      "type": "array",
+      "description": "Types of memory to add: ['stream', 'stream_v2', 'persona', 'persona_v2']",
+      "default": ["stream_v2"],
+      "env": "MEMORY_ADD_LIST"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "human-like-mem-openclaw-plugin",
+  "version": "0.1.0",
+  "description": "Long-term memory plugin for OpenClaw - AI Social Memory Integration",
+  "main": "index.js",
+  "type": "module",
+  "files": [
+    "index.js",
+    "openclaw.plugin.json",
+    "README.md",
+    "README_ZH.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "plugin",
+    "memory",
+    "ai",
+    "long-term-memory",
+    "ai-social",
+    "human-like-memory"
+  ],
+  "author": "hanlaomo",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.ttyuyin.com/personalization_group/human-like-mem-openclaw-plugin.git"
+  },
+  "bugs": {
+    "url": "https://gitlab.ttyuyin.com/personalization_group/human-like-mem-openclaw-plugin/-/issues"
+  },
+  "homepage": "https://gitlab.ttyuyin.com/personalization_group/human-like-mem-openclaw-plugin#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}