Skip to content

feat: add persistent local memory plugin for OpenClaw (memos-local-openclaw)#1182

Merged
CaralHsi merged 16 commits intoMemTensor:mainfrom
tangbotony:native_memos
Mar 9, 2026
Merged

feat: add persistent local memory plugin for OpenClaw (memos-local-openclaw)#1182
CaralHsi merged 16 commits intoMemTensor:mainfrom
tangbotony:native_memos

Conversation

@tangbotony
Copy link
Contributor

Description

Introduce MemOS (memos-local-openclaw-plugin), a fully local OpenClaw memory plugin that gives AI agents persistent memory, intelligent task summarization, self-evolving skills, and multi-agent collaboration.

Problem: OpenClaw agents have no persistent memory across sessions. Every conversation starts from scratch — the agent forgets previous interactions, repeats mistakes, and cannot learn from past experience. There is no mechanism to organize conversations into structured knowledge, distill successful executions into reusable skills, or share knowledge across multiple agents.

Solution — Four Intelligent Pipelines:

  1. Memory Write Pipeline — Auto-captures every conversation via agent_end hook → semantic chunking → LLM summarization → vector embedding → smart deduplication (content-hash + Top-5 vector + LLM judge: DUPLICATE/UPDATE/NEW) → SQLite + FTS5 storage

  2. Task Summarization Pipeline — Per-turn LLM topic boundary detection (warm-up: 1 user turn, 2h idle timeout) → structured summaries (Goal → Steps → Result → Key Details) → quality filtering → full CRUD from Viewer

  3. Skill Evolution Pipeline — Rule filter → LLM evaluation → SKILL.md generation with scripts + evals → quality scoring (0-10) → auto-upgrade on similar tasks (refine/extend/fix) → version management → 3-level LLM fallback chain (skillSummarizer → summarizer → OpenClaw native model)

  4. Smart Retrieval Pipeline — FTS5 + vector hybrid search → RRF fusion → MMR diversity reranking → recency decay → LLM relevance filter → auto-recall via before_agent_start hook

Additional capabilities:

  • Multi-agent collaboration — Memory isolation via owner field + public memory + skill sharing/publishing
  • Memory Migration (Reconnect 🦞) — One-click import from OpenClaw native memories with smart dedup, pause/resume, configurable agent parallelism (1-8)
  • Memory Viewer — 7-page web dashboard (Memories, Tasks, Skills, Analytics, Logs, Import, Settings) with full CRUD, i18n, light/dark theme, password protection
  • 12 smart agent toolsauto_recall, memory_search, memory_get, memory_timeline, memory_write_public, task_summary, skill_get, skill_install, skill_search, skill_publish, skill_unpublish, memory_viewer
  • Tiered models — Embedding (lightweight) / Summarizer (mid-tier) / Skill generation (high-quality), each independently configurable
  • Zero-config start — Falls back to local embedding + rule-based summarization when no API keys configured
  • 100% local — All data in local SQLite, zero cloud uploads, localhost-only Viewer

Related Issue (Required): Fixes #1181

Type of change

  • New feature (non-breaking change which adds functionality)
  • Documentation update

How Has This Been Tested?

  • Unit Test
  • Test Script Or Test Steps (please provide)

Unit tests (npm test in apps/memos-local-openclaw/):

  • tests/policy.test.ts — Retrieval strategy, search filtering, evidence extraction
  • tests/recall.test.ts — RRF fusion, recency decay correctness
  • tests/capture.test.ts — Message filtering, evidence block stripping, self-tool exclusion
  • tests/storage.test.ts — SQLite CRUD, FTS5, vector storage, content hash dedup
  • tests/chunker.test.ts — Semantic chunking for code blocks, paragraphs, function bodies
  • tests/task-processor.test.ts — Task boundary detection, skip logic, summary generation
  • tests/multi-agent.test.ts — Multi-agent memory isolation, owner filtering, public sharing
  • tests/integration.test.ts — End-to-end ingestion and retrieval pipeline

Manual testing:

  1. Install plugin via openclaw plugins install . → start gateway → verify Memory Viewer at http://127.0.0.1:18799
  2. Have conversations with OpenClaw agent → verify auto-capture, dedup, task detection, skill generation
  3. Test memory migration from OpenClaw native memories → verify dedup, resume, post-processing
  4. Test multi-agent scenarios → verify memory isolation and skill sharing
  5. Test task/skill CRUD operations from Viewer list cards (edit, delete, retry, visibility toggle)
  6. Test LLM fallback chain by disabling primary model → verify automatic fallback to next level

Checklist

  • I have performed a self-review of my own code | 我已自行检查了自己的代码
  • I have commented my code in hard-to-understand areas | 我已在难以理解的地方对代码进行了注释
  • I have added tests that prove my fix is effective or that my feature works | 我已添加测试以证明我的修复有效或功能正常
  • I have created related documentation issue/PR in MemOS-Docs (if applicable) | 我已在 MemOS-Docs 中创建了相关的文档 issue/PR(如果适用)
  • I have linked the issue to this PR (if applicable) | 我已将 issue 链接到此 PR(如果适用)
  • I have mentioned the person who will review this PR | 我已提及将审查此 PR 的人

Reviewer Checklist

tangbotony and others added 16 commits March 7, 2026 22:33
Reorganize project structure by moving the openwork-memos-integration
module under the apps/ directory for consistency.

Made-with: Cursor
Move the openwork-memos-integration module to apps/ directory as part
of the monorepo restructuring.

Made-with: Cursor
- Extract agentId from OpenClaw events, pass owner to captureMessages,
  ownerFilter to search/recall/dedup across the full pipeline
- Task creation now uses per-agent owner instead of hardcoded "agent:main"
- Add owner filter to getActiveTask, getAllActiveTasks, getUnassignedChunks,
  listTasks in sqlite.ts for proper task-level isolation
- Dedup (findDuplicate/findTopSimilar) now scopes to agent's own + public
  embeddings to prevent cross-agent deduplication
- Fix cursor key to include agentId, preventing shared session cursor
  conflicts in multi-agent scenarios
- On gateway restart, initialize cursor from last user message instead of
  zero to avoid re-ingesting entire session history
- Add multi-agent isolation tests for task owner filtering
- Bump version to 0.3.20

Made-with: Cursor
- Update root .gitignore to whitelist apps/ directory files (json, html,
  ts, etc.) that were previously excluded by the global *.json rule
- Update memos-local-openclaw .gitignore to exclude package-lock.json,
  www/, docs/, ppt/, .DS_Store, and database files
- Remove unnecessary www/docs symlink from tracking
- Add missing package.json, tsconfig.json, openclaw.plugin.json to git
- Add previously ignored config files for openwork-memos-integration

Made-with: Cursor
- Remove video-thumbnail.png (4.6MB), font files (280KB), lock files
  (258KB), and usecase image assets from git tracking
- Add .gitignore for openwork-memos-integration to prevent re-adding
  binary assets, lock files, and build artifacts
- Add comprehensive Development Guide to memos-local-openclaw README
  covering prerequisites, project structure, build, test, local dev
  workflow, publishing, and utility scripts

Made-with: Cursor
fix(memos-local-openclaw): flush ingest work before shutdown
fix(memos-local-openclaw): honor memory_search maxResults
fix(memos-local-openclaw): sanitize captured metadata and evidence
fix(memos-local-openclaw): enforce owner isolation for memory tools
…l evolution improvements

- Add task/skill edit, delete, retry-skill-generation on list cards
- Fix task boundary detection: per-turn LLM judgment with warm-up=1
- Fix detectAndProcess to not blindly assign all unassigned chunks
- Strengthen topic judge prompt to reduce false NEW splits
- Add LLM fallback chain (strongCfg → cfg → OpenClaw native model)
- Add skill evolver FK constraint safety checks
- Remove redundant edit/delete buttons from detail modals
- Add input validation for /api/memory content field
- Add /api/search minScore filter (0.64) and keyword fallback
- Shared LLM call utility (src/shared/llm-call.ts)

Made-with: Cursor
…stall guidance

- Add Step 0: proactive C++ build tools install before plugin install
- Clarify Windows users usually don't need build tools (prebuilt binaries)
- Document per-turn LLM topic judge, warm-up=1, Task/Skill CRUD on cards
- Add LLM fallback chain details (skillSummarizer → summarizer → OpenClaw native)
- Add viewer search minScore 0.64 and keyword fallback docs
- Add agent parallelism (1-8 concurrency) for import
- Add shared/llm-call.ts to project structure
- Link to better-sqlite3 official troubleshooting in all install sections

Made-with: Cursor
@tangbotony tangbotony self-assigned this Mar 9, 2026
@tangbotony tangbotony changed the title memos-local-openclaw feat: add persistent local memory plugin for OpenClaw (memos-local-openclaw) Mar 9, 2026
@CaralHsi CaralHsi merged commit 1724d26 into MemTensor:main Mar 9, 2026
32 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

2 participants