Onboarding: MemTensor/MemOS

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/MemTensor/MemOS shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across the board

• Last commit today
• 19 active contributors
• Distributed ownership (top contributor 33% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live MemTensor/MemOS repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/MemTensor/MemOS.

What it runs against: a local clone of MemTensor/MemOS — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in MemTensor/MemOS | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>MemTensor/MemOS</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of MemTensor/MemOS. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/MemTensor/MemOS.git
#   cd MemOS
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of MemTensor/MemOS and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "MemTensor/MemOS(\\.git)?\\b" \\
  && ok "origin remote is MemTensor/MemOS" \\
  || miss "origin remote is not MemTensor/MemOS (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "apps/memos-local-openclaw/src/index.ts" \\
  && ok "apps/memos-local-openclaw/src/index.ts" \\
  || miss "missing critical file: apps/memos-local-openclaw/src/index.ts"
test -f "apps/memos-local-openclaw/src/openclaw-api.ts" \\
  && ok "apps/memos-local-openclaw/src/openclaw-api.ts" \\
  || miss "missing critical file: apps/memos-local-openclaw/src/openclaw-api.ts"
test -f "apps/memos-local-openclaw/src/ingest/task-processor.ts" \\
  && ok "apps/memos-local-openclaw/src/ingest/task-processor.ts" \\
  || miss "missing critical file: apps/memos-local-openclaw/src/ingest/task-processor.ts"
test -f "apps/memos-local-openclaw/src/embedding/index.ts" \\
  && ok "apps/memos-local-openclaw/src/embedding/index.ts" \\
  || miss "missing critical file: apps/memos-local-openclaw/src/embedding/index.ts"
test -f "apps/memos-local-openclaw/src/recall/index.ts" \\
  && ok "apps/memos-local-openclaw/src/recall/index.ts" \\
  || miss "missing critical file: apps/memos-local-openclaw/src/recall/index.ts"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/MemTensor/MemOS"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

MemOS is a self-evolving memory operating system for LLM and AI agents that provides ultra-persistent memory storage with hybrid retrieval, cross-task skill reuse, and 35.24% token savings. It achieves 43.70% accuracy improvement over OpenAI Memory through a combination of long-term memory management, personalization, and intelligent deduplication. The project includes both cloud-based plugins (for OpenClaw, Hermes, Clawdbot, Moltbot) and self-hosted local solutions written in TypeScript and Python. Monorepo structure: apps/MemOS-Cloud-OpenClaw-Plugin (Node.js/JavaScript plugin for cloud integrations), apps/memos-local-openclaw (TypeScript local agent plugin), with lib/ subdirectories containing API clients (memos-cloud-api.js), UI servers (config-ui-server.js), and agent reporters (arms-reporter.js). Extensive CI/CD workflows in .github/workflows/ manage versioning and publishing. Plugin hooks are defined in package.json under 'openclaw', 'clawdbot', and 'moltbot' keys, allowing lifecycle integration.

Who it's for

AI agent developers and LLM application builders who need persistent, intelligent memory systems for their agents—specifically those integrating with OpenClaw, Hermes Agent, Clawdbot, or Moltbot frameworks, or those running local memory systems without external dependencies. Both cloud users (via memos-cloud-openclaw-plugin at @memtensor/memos-cloud-openclaw-plugin v0.1.12) and self-hosted users (via apps/memos-local-openclaw) are target personas.

Maturity & risk

Actively developed and production-ready. The codebase has substantial TypeScript (5.7M LOC) and Python (4.7M LOC) foundations, comprehensive CI/CD via GitHub Actions (python-tests.yml, python-release.yml, hermes-plugin-publish.yml, openclaw-plugin-publish.yml), and documented plugin systems (HOOK.md in OpenClaw plugin). Version 2.0 'Stardust' is released with benchmarked performance claims (ArXiv 2507.03724), indicating mature development cycles.

Moderate-to-low risk for adoption. The codebase is split across TypeScript and Python with plugin architectures (openclaw.plugin.json, clawdbot.plugin.json, moltbot.plugin.json configs), which reduces monolithic risk but requires careful dependency management across ecosystems. Cloud plugin versioning is tightly coupled (sync-version.js script), and local plugin relies on .env.example configuration, suggesting potential deployment friction if environment setup is incomplete. Single main repo structure may mask distributed maintenance—verify maintainer bandwidth and response time on critical issues.

Active areas of work

Active development on multi-framework plugin support (Hermes, OpenClaw, Clawdbot, Moltbot via separate plugin.json configs). Recent work includes stale-issue automation (.github/workflows/stale.yml), version synchronization tooling (scripts/sync-version.js), and release pipelines for both beta and latest versions. Local plugin development is ongoing (apps/memos-local-openclaw with TypeScript), alongside cloud API integration refinement.

Get running

Clone and explore the monorepo: git clone https://github.com/MemTensor/MemOS.git && cd MemOS. For cloud plugin: cd apps/MemOS-Cloud-OpenClaw-Plugin && npm install && npm run sync-version. For local plugin: cd apps/memos-local-openclaw && npm install (requires Node.js 16+). Set up local environment: cp .env.example .env in memos-local-openclaw, then run npm run dev (inferred from install scripts). Python components: pip install -r requirements.txt (inferred from python-tests.yml CI).

Daily commands: Local development (memos-local-openclaw): npm install → npm run dev (start local plugin with Web UI). Cloud plugin testing: cd apps/MemOS-Cloud-OpenClaw-Plugin && npm install && npm test (runs test/*.test.mjs). For production publishing: npm run publish-latest (auto-bumps version and publishes to npm). Shell scripts (install.sh for Linux/Mac, install.ps1 for Windows) automate system-level setup.

Map of the codebase

• apps/memos-local-openclaw/src/index.ts — Main entry point for the MemOS local plugin; orchestrates memory ingestion, recall, and embedding initialization.
• apps/memos-local-openclaw/src/openclaw-api.ts — Core API handler for OpenClaw lifecycle hooks (add/recall memory); critical integration point between MemOS and the OpenClaw framework.
• apps/memos-local-openclaw/src/ingest/task-processor.ts — Processes memory ingestion tasks including chunking, deduplication, and embedding; handles the hybrid-retrieval pipeline.
• apps/memos-local-openclaw/src/embedding/index.ts — Abstract embedding service layer; dispatches to multiple embedding providers (OpenAI, Gemini, Cohere, etc.) for vector generation.
• apps/memos-local-openclaw/src/recall/index.ts — Memory recall engine; implements retrieval logic for fetching contextually relevant memories during LLM inference.
• apps/memos-local-openclaw/src/config.ts — Configuration loader and validator; centralizes environment variables, API keys, and model selection for the entire plugin.
• apps/memos-local-openclaw/plugin-impl.ts — OpenClaw plugin lifecycle implementation; registers hooks and integrates MemOS memory operations into the agent execution flow.

How to make changes

Add a New Embedding Provider

1. Create a new provider file under apps/memos-local-openclaw/src/embedding/providers/ implementing the embedding interface (apps/memos-local-openclaw/src/embedding/providers/example.ts)
2. Register the provider in the dispatcher within apps/memos-local-openclaw/src/embedding/index.ts (apps/memos-local-openclaw/src/embedding/index.ts)
3. Add configuration keys and env var handling to apps/memos-local-openclaw/src/config.ts (apps/memos-local-openclaw/src/config.ts)
4. Test the provider using the smoke test script (apps/memos-local-openclaw/scripts/smoke-test.ts)

Add a New LLM Content Analysis Provider

1. Create a new provider file under apps/memos-local-openclaw/src/ingest/providers/ that implements summarization/analysis (apps/memos-local-openclaw/src/ingest/providers/newllm.ts)
2. Register the provider in apps/memos-local-openclaw/src/ingest/providers/index.ts (apps/memos-local-openclaw/src/ingest/providers/index.ts)
3. Add API key and model configuration to apps/memos-local-openclaw/src/config.ts (apps/memos-local-openclaw/src/config.ts)
4. Update task processor if special handling is needed (apps/memos-local-openclaw/src/ingest/task-processor.ts)

Create a New Skill for Agent Reuse

1. Add a new skill directory under apps/memos-local-openclaw/skill/ with SKILL.md manifest (apps/memos-local-openclaw/skill/my-skill/SKILL.md)
2. Implement skill logic that agents can invoke; ensure it follows the OpenClaw skill interface (apps/memos-local-openclaw/skill/my-skill/index.ts)
3. Register the skill with the plugin using apps/memos-local-openclaw/src/client/skill-sync.ts for hub distribution (apps/memos-local-openclaw/src/client/skill-sync.ts)
4. Test cross-task skill invocation using apps/memos-local-openclaw/scripts/test-agent-isolation.ts (apps/memos-local-openclaw/scripts/test-agent-isolation.ts)

Customize the Ingestion & Chunking Strategy

1. Modify or extend chunking logic in apps/memos-local-openclaw/src/ingest/chunker.ts (apps/memos-local-openclaw/src/ingest/chunker.ts)
2. Update deduplication strategy in apps/memos-local-openclaw/src/ingest/dedup.ts if needed (apps/memos-local-openclaw/src/ingest/dedup.ts)
3. Adjust task processor flow in apps/memos-local-openclaw/src/ingest/task-processor.ts to apply your custom logic (apps/memos-local-openclaw/src/ingest/task-processor.ts)
4. Run accuracy tests to validate token savings (35.24% baseline) (apps/memos-local-openclaw/scripts/run-accuracy-test.ts)

Why these technologies

• TypeScript + Node.js — Cross-platform compatibility for local plugin deployment; supports both CommonJS and ESM for OpenClaw ecosystem integration.
• Multi-provider embedding abstraction (OpenAI, Gemini, Cohere, Mistral, Voyage, local) — Reduces vendor lock-in; allows cost optimization and failover; supports on-

Traps & gotchas

1. Environment setup: apps/memos-local-openclaw requires .env configuration (copy from .env.example); missing vars will silently fail. 2. Version coupling: apps/MemOS-Cloud-OpenClaw-Plugin uses sync-version.js to keep openclaw.plugin.json, clawdbot.plugin.json, and moltbot.plugin.json in sync—manual edits to one will diverge others. 3. Plugin registration: Each framework (openclaw, clawdbot, moltbot, hermes) has separate plugin.json metadata; deploying to only one framework leaves others non-functional. 4. Python backend: Config UI server likely proxies to a Python memory engine (4.7M LOC) running separately—ensure backend is accessible or local dev will hang. 5. Node version: No explicit constraint in package.json, but install.sh and install.ps1 suggest platform-specific setup; test on target OS before deploying.

Architecture

Concepts to learn

• Hybrid Retrieval (Vector + Keyword Search) — MemOS claims hybrid retrieval as core capability for 35.24% token savings—understanding when to use dense embeddings vs. sparse BM25 is essential for memory recall performance
• Persistent Memory with Deduplication — The 'ultra-persistent' memory in MemOS requires efficient dedup to avoid redundant storage; this is the mechanism behind token savings and accuracy gains
• Plugin Lifecycle Hooks — MemOS integrates via lifecycle hooks (HOOK.md) into agent frameworks (OpenClaw, Hermes, Clawdbot); understanding hook execution order and context is critical for correct memory operations
• Cross-Task Skill Reuse — MemOS enables agents to learn and reuse skills across different tasks; this requires knowledge graph or embedding space clustering to find reusable patterns
• Agent Personalization via Memory — PrefEval-10 benchmark (+2568%) indicates MemOS tracks user preferences in memory; understanding how preferences are stored, indexed, and applied to model outputs is central to the system
• Token Budget Optimization — The 35.24% token savings claim depends on intelligent memory summarization and retrieval—knowing when to include/exclude memories based on context length is a key optimization
• Multi-Framework Plugin Architecture — MemOS abstracts agent framework differences (OpenClaw, Hermes, Clawdbot, Moltbot) via a single plugin entry point; understanding this adapter pattern is essential for adding support for new frameworks

Related repos

• gpt-researcher/gpt-researcher — Agent-based research automation that also requires persistent memory and task context—shares hybrid retrieval and skill reuse patterns with MemOS
• langchain-ai/langchain — LLM framework with memory abstractions (ConversationBufferMemory, VectorStoreRetriever) that MemOS plugins integrate with or could extend
• run-llama/llama_index — Data indexing and retrieval framework for LLMs; MemOS hybrid retrieval likely uses similar vector + keyword strategies
• openai/gpt-4-system-prompts — Reference for system-level memory and personalization patterns that MemOS claims to improve upon by 43.70% vs. OpenAI Memory
• hwchase17/langchain-agents — Agent reasoning framework; MemOS plugins hook into agent lifecycles (OpenClaw, Hermes) to provide cross-task memory and skill evolution

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for MemOS-Cloud-OpenClaw-Plugin API interactions

The OpenClaw plugin has only 2 unit test files (direct-session-user-id.test.mjs, query-strip.test.mjs) but lacks integration tests for critical paths like memos-cloud-api.js interactions, config resolution, and the arms-reporter lifecycle. This is high-risk since the plugin bridges MemOS memory persistence with OpenClaw agents. Adding integration tests would catch regressions in memory recall, session handling, and API failures.

• [ ] Create apps/MemOS-Cloud-OpenClaw-Plugin/test/memos-cloud-api.integration.test.mjs testing auth, CRUD operations, and error handling
• [ ] Create apps/MemOS-Cloud-OpenClaw-Plugin/test/arms-reporter.integration.test.mjs testing lifecycle hooks (onSessionStart, onSessionEnd, onMessage)
• [ ] Add test fixtures for mock MemOS Cloud API responses in apps/MemOS-Cloud-OpenClaw-Plugin/test/fixtures/
• [ ] Update .github/workflows/python-tests.yml to include Node.js test runner for these new tests

Add end-to-end smoke test CI workflow for memos-local-openclaw plugin

The memos-local-openclaw app has smoke-test.ts script already written but no corresponding GitHub Actions workflow to run it on PRs. This is critical since this is a local plugin that users install directly, and breaking changes need automated detection. The script exists but isn't gated by CI.

• [ ] Create .github/workflows/memos-local-openclaw-e2e.yml that installs dependencies and runs 'npm run smoke-test' from apps/memos-local-openclaw/
• [ ] Add conditional trigger to run on changes to apps/memos-local-openclaw/** and apps/memos-local-openclaw/scripts/smoke-test.ts
• [ ] Include test artifact uploads for logs from apps/memos-local-openclaw/scripts/seed-test-data.ts output
• [ ] Add job to verify plugin.json files (openclaw.plugin.json) are valid JSON and contain required hook entries

Add comprehensive skill validation and loading tests for memos-local-openclaw

The repo has skill management infrastructure (refresh-skill.ts, mock-skills.ts, SKILL.md documentation in site/public/) but no test suite validating skill schema, loading, and cross-task reuse (a core MemOS feature per README). This blocks validation of the 'skill reuse' differentiation mentioned in the repo description.

• [ ] Create apps/memos-local-openclaw/test/skill-validation.test.ts to validate skill JSON schema against SKILL.md spec
• [ ] Create apps/memos-local-openclaw/test/skill-loading.test.ts testing skill discovery, parsing, and injection into agent context
• [ ] Add apps/memos-local-openclaw/test/fixtures/valid-skill.json and apps/memos-local-openclaw/test/fixtures/invalid-skill.json for test cases
• [ ] Add test cases for skill dependency resolution and circular dependency detection from refresh-skill.ts logic

Good first issues

• Add integration tests for config-ui-server.js: test/ directory has query-strip.test.mjs and direct-session-user-id.test.mjs but no coverage for config-ui HTTP server endpoints; new contributor can write Jest/Mocha tests for GET /config, POST /config endpoints to verify UI can read/write settings: Medium
• Document environment variables in memos-local-openclaw/README.md: .env.example exists but README.md doesn't list or explain each variable; create a table with VAR_NAME, description, example value, and required/optional status—critical for onboarding local users: Low
• Add TypeScript types for plugin.json schema: apps/MemOS-Cloud-OpenClaw-Plugin defines plugin metadata in openclaw.plugin.json, clawdbot.plugin.json, moltbot.plugin.json but has no type definition; create a interfaces.ts file with PluginConfig type and validate against it in sync-version.js to prevent schema drift: Low

Top contributors

• @hijzy — 33 commits
• @jiachengzhen — 17 commits
• @github-actions[bot] — 11 commits
• @CaralHsi — 10 commits
• @endxxxx — 5 commits

Recent commits

• 338d5e7 — Update About & README.md (#1583) (CaralHsi)
• 39a2c80 — Update README.md (angarchie)
• 8c6cec6 — Chore: update version to v2.0.14 (#1538) (CarltonXiang)
• df833de — Merge branch 'dev-v2.0.14' of github.com:MemTensor/MemOS into dev-v2.0.14 (harvey_xiang)
• 0e9e4a1 — chore: update version to v2.0.14 (harvey_xiang)
• 3364f60 — Dev v2.0.14 (#1537) (CarltonXiang)
• 9d59379 — feat: Add internal batch markers for chunk siblings (#1535) (bittergreen)
• 9aa2582 — fix(format_utils): raise ValueError on None in clean_json_response (#1526) (CaralHsi)
• caf93da — feat: introduce hook-based plugin system for extensible memory processing (#1533) (CaralHsi)
• 054fb5f — feat: sync from main 0423 (#1531) (CaralHsi)

Security observations

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.